Troubleshooting (self-hosted)
Fix common self-hosted SlugBase install and runtime problems: secrets, URLs, database, proxy, and first-run issues.
Before you dig in
Most production failures come from environment variables or URL mismatch behind a reverse proxy. Confirm values with Configuration and Reverse proxy and HTTPS. For a clean first install, follow First run setup.
Check container or process logs when the server exits immediately or API calls fail—startup validation prints clear errors for missing or weak secrets.
Server exits on startup
JWT_SECRET and ENCRYPTION_KEY are required and must each be at least 32 characters and not the documented placeholder. In NODE_ENV=production, SESSION_SECRET is also required (minimum 32 characters). Generate values safely (see Configuration), update your env file or orchestration secrets, and restart.
The server listens on PORT (default 5000). Ensure nothing else uses that port, or set PORT to a free port and point your reverse proxy at it. In Docker, map the host port to the container PORT.
Login, cookies, and HTTPS
Set BASE_URL and FRONTEND_URL to the exact origin users use in the browser (including https://). Cookies are Secure when NODE_ENV=production and BASE_URL starts with https://. Mismatched scheme or host breaks sessions. See Reverse proxy and HTTPS.
The app trusts one proxy hop (X-Forwarded-*). Your proxy should forward Host, X-Forwarded-Proto, and X-Forwarded-For. Keep BASE_URL aligned with the public hostname.
Set FRONTEND_URL to your UI origin, or add extra origins in CORS_EXTRA_ORIGINS. A typical single-container self-hosted build serves the SPA and API on the same origin, which avoids CORS. Details in Configuration.
Database and data
Ensure the process can read and write DB_PATH (Dockerfile default /app/data/slugbase.db). Mount a persistent volume for the data directory so the file survives container restarts. See Docker Compose.
Set DB_TYPE=postgresql and either DATABASE_URL or DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD. Verify network reachability from the SlugBase container or host. Migrations run automatically on startup.
The database is already initialized. For a true fresh start you need an empty database or a new SQLite file path—not a reused volume from an old install. See First run setup.
OIDC and email
Provider settings in Admin → OIDC Providers must match your IdP. Callback URLs must use the same public BASE_URL as users (including https://). Follow OIDC.
Configure SMTP under Admin → Settings. Without working outbound mail, reset links cannot be sent. See SMTP.
Slugs and /go/ links
Opening a slug requires being signed in; unauthenticated users are sent to login first. The bookmark needs Enable Forwarding and a unique Slug. See Slugs overview and Go preferences.
API documentation and health checks
Set SLUGBASE_API_DOCS=false to disable the UI at /api-docs. OpenAPI JSON/YAML routes may still be available unless you restrict them at the proxy. See Configuration.
Request /api/health through your public URL and expect a successful response when the app is up. Use this for load balancers after following Reverse proxy and HTTPS.
Related
Last updated Apr 3, 2026
Built with Documentation.AI