Troubleshooting
General
A service won't start / exits immediately. No secret in SeyalRun has a default value — every service checks its required environment variables at startup and refuses to boot if any are missing. Check the container's logs for which variable is unset; compare against .env.example and the Configuration Reference.
Browser can't reach the login page / CORS errors in the console.FRONTEND_ORIGIN must exactly match the URL you're browsing to (including scheme and port). A mismatch causes api-gateway to reject the request as cross-origin.
TLS certificate warnings. TLS_CERT_PATH/TLS_KEY_PATH point edge-proxy at a cert/key pair. A self-signed cert is fine for staging/local — accept the browser warning once. For production, use a Let's Encrypt or internal-CA-issued cert.
Page loads inside an iframe but the parent site refuses to render it / console shows a frame-ancestors CSP violation. FRAME_ANCESTORS in SeyalRun's .env must list the embedding site's origin (e.g. https://zabbix.example.com). Restart edge-proxy after changing it.
Database
ops/init-db.sh fails to connect. Confirm DB_HOST/DB_PORT are reachable from wherever you're running the script (not necessarily the same network the containers use), and that DB_USER has permission to create databases on that instance, not just connect to existing ones.
A service's own tables are missing after ops/init-db.sh. That script only creates the four databases and imports the static schema into seyalrun_identity/seyalrun_inventory. Every service's own tables (including all of terminal/automation) come from that service's Alembic migrations — run the migration loop in step 4 of Manual Setup.
Zabbix self-monitoring
Master item shows "Not supported" / no data. Confirm {$SEYALRUN.MONITOR.URL} matches your EDGE_HTTPS_PORT exactly and that {$SEYALRUN.MONITOR.TOKEN} matches ZABBIX_WEBHOOK_HMAC_SECRET — this endpoint bypasses api-gateway, so a mismatched token is the most common cause of a silently-failing poll.
Zabbix frontend module
See the full troubleshooting table in Zabbix Frontend Module — common symptoms:
| Symptom | Likely cause |
|---|---|
| "Cannot load module at: seyalrun" | relative_path must be modules/<dir-name>, root-relative to the Zabbix frontend directory — not just the module's folder name. Fix via Scan directory rather than a raw DB/API insert. |
| Menu loads (HTTP 200) but content area is blank | seyalrun_public_url isn't reachable from the visitor's browser (commonly left as 127.0.0.1). Set it to the box's real IP/hostname. |
Still blank after fixing seyalrun_public_url | Self-signed TLS on edge-proxy — browsers fail silently inside an iframe instead of showing a click-through warning. Open the SeyalRun URL directly in a new tab first, accept the cert warning, then reload the Zabbix page. |
| No SeyalRun menu item at all | Module not Enabled under Administration → General → Modules, or the frontend needs a hard refresh. |
| "module is not configured yet" | config.php missing, or seyalrun_url/module_secret blank. |
| "SeyalRun is unavailable right now" | seyalrun_url unreachable from the Zabbix frontend's PHP process, a TLS cert curl won't trust, or module_secret doesn't match ZABBIX_MODULE_SECRET. |
| Iframe loads but shows the login page instead of the embedded page | The sso_code exchange failed or expired (>120s between mint and load) — check clock skew and identity-service logs for sso-exchange rejections. |
| SSH Hosts page is empty | The current Zabbix user has no hosts with write permission — Zabbix's own permission model, not a SeyalRun setting. |
| Terminal icon opens SeyalRun but access is denied | Working as intended — Zabbix write access doesn't imply a SeyalRun grant. Grant it in SeyalRun's Authorizations admin page. |
Still stuck?
Open an issue on GitHub with your SeyalRun version, deployment method (quick-install vs. manual), and the relevant service's logs (docker compose logs <service>).