Troubleshooting¶
Start with the Relay version, active data path, exact error and time. Check server logs and browser developer tools. Remove tokens, passwords, private messages and connection strings before sharing diagnostic output. The audit report distinguishes tested behavior from source review.
Startup and permissions¶
| Symptom | Checks and next step |
|---|---|
| Address already in use | Stop the duplicate service or select another port; confirm the configured host exists locally |
| Permission denied | Confirm the service UID can traverse/write the data directory and read TLS files; check container UID mapping, not only host ownership |
| Blank page or missing assets | Confirm public/ was built and the server runs from the correct working directory; hard-reload after an upgrade |
users/ does not exist |
Run relay start once with the same RELAY_HOME, then use relay users add |
| YAML change has no effect | Inspect admin-overrides.json and service -c flags, then restart; see precedence |
| Restart button stops the service | Configure the supervisor to restart after exit code 0; the button does not launch a replacement process |
Login and account recovery¶
Use the current server log's setup token; a restart before setup replaces it. Once any account exists, use normal sign-in. Check whether the account is locked, local MFA is required, or the account belongs to OIDC. A password reset retains enrolled factors.
For a rejected authenticator code, synchronize the device clock, try a fresh six-digit code, and restart a challenge older than five minutes. Use a saved one-time recovery code if the authenticator is lost. For key failures, confirm HTTPS, the original RP hostname, and browser/device support. See account recovery.
WebSocket disconnections¶
If the page loads but sign-in stalls or repeatedly reconnects, inspect /ws in the browser Network panel. It should return 101 Switching Protocols. Check proxy upgrade headers, upstream connectivity, TLS, origin/host forwarding, and idle timeouts. A 403 may indicate an origin or authentication-policy problem; inspect server logs before changing trust settings. Use the complete proxy example.
Distinguish browser-to-Relay disconnection from Relay-to-IRC disconnection: a private Relay account normally remains on IRC when its browser closes. Check the network lobby and Network diagnostics… before changing IRC credentials.
IRC authentication¶
Check hostname, port, TLS and Only allow trusted certificates. Server Password is not the SASL account password. Choose Username + password (SASL PLAIN) and enter the registered IRC account, or register the generated certificate fingerprint with the IRC network for Client certificate (SASL EXTERNAL). Inspect the network lobby's SASL/nickname errors. Credentials for your Relay login do not log you into IRC. See Networks and connections.
Missing history, search or threads¶
Confirm the account saves logs and messageStorage includes SQLite or PostgreSQL. Check the active home/database connection, import results and retention policy. Text logs are not searchable through the structured-history UI. maxHistory limits in-memory channel messages separately from retained database history. IRC history retrieval additionally depends on server capability and the history it retains. For replies with local fallback IDs through bouncers, read compatibility limitations.
Notifications¶
Check Settings > Notifications, the conversation's mute/notification settings, browser permission for this exact origin, OS notification settings and do-not-disturb. Push needs a supported secure browser/service worker; iOS installation requirements can differ from desktop. Play a sound preview after interacting with the page. A successful in-window alert does not prove OS push works. Old/backfilled messages may be intentionally suppressed. See Notifications.
Uploads and shared links¶
Check private mode, administrator enablement, Relay's KiB file limit and the proxy's total request-body limit. A 413 usually means a size limit; a missing/expired URL may be expected cleanup. Check disk space, data-directory permissions, configured public base URL and the server log. DCC additionally needs positive resource budgets and explicit acceptance. Desktop Catbox uploads are managed outside Relay. See Uploads and sharing.
Before retrying a destructive operation
Preserve the original database and error output before repeating migration or retention commands. Check the backup and restore procedure and verify which account and data directory the command targets.