Troubleshooting
Common problems when running OpenDash, what usually causes them, and how to fix each.
Startup
| Symptom | Likely cause | Fix |
|---|---|---|
web won't start in production | Email, a valid secret, base URL or trusted origins is missing | Set EMAIL_FROM with RESEND_API_KEY or SMTP_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL and BETTER_AUTH_TRUSTED_ORIGINS |
| A new instance refuses to start | Invite-only with no first admin | Set OPENDASH_BOOTSTRAP_ADMIN_EMAIL |
extension "vector" does not exist | The Postgres image lacks pgvector | Use a pgvector image, such as pgvector/pgvector:pg17, or enable the extension on your managed Postgres |
| A dashboard says "Dashboards can't open here" | No frames origin | Set OPENDASH_FRAMES_URL when the web image is built and when it runs. See Configuration |
relation "pgboss.job" does not exist | The job queues aren't installed | Run the setup service again (or pnpm db:migrate in development) |
Sign-in
| Symptom | Likely cause | Fix |
|---|---|---|
| Sign-in is refused | BETTER_AUTH_URL or a trusted origin is plain HTTP | Put a TLS proxy in front, or use the Caddy profile |
| No sign-in email arrives | Email provider rejects the sender | Verify the sender's domain with Resend, or check SMTP_URL and TLS |
| Everyone shares one rate limit | A proxy appends to X-Forwarded-For and isn't trusted | Set OPENDASH_TRUSTED_PROXIES |
Answers and sources
| Symptom | Likely cause | Fix |
|---|---|---|
| Answers never update while they're written | LISTEN is going through a transaction pooler | Point DATABASE_DIRECT_URL at a direct or session-mode connection |
| "No worker has picked up the check yet" when connecting a source | Only web is running | Start the worker service |
| A source fails its TLS check | The certificate isn't from a public CA, or doesn't name the host you typed | Paste your CA's certificate on the connect form; type the host the certificate names |
| A ClickHouse source refuses outer joins | The server has join_use_nulls = 0 and the user is readonly = 1 | Give the user readonly = 2, or set join_use_nulls = 1 on the server |
| No models to choose from | No provider key | Set a provider key on both images, or add one under Settings → AI |
Still stuck?
- Search the GitHub issues, or open one with your version, how you deploy, and the relevant log lines (both processes log JSON to stdout).
- Security problems go through the private process in Security and telemetry, never a public issue.
Enterprise features
Single sign-on, directory sync and the tamper-evident audit log, from the source-available ee/ directory. How licensing works and how to set each one up.
Architecture
The whole system on one page. What runs, how a question becomes a checked answer, and the design decisions that shape the code.