Skip to content
BurnerByte

Troubleshooting

Common issues and solutions when running BurnerByte.

Emails Not Being Received

Symptoms: Inboxes are created but no emails arrive.

Check these in order:

  1. SMTP server running? — Verify cmd/smtpd is running and listening on port 2525
  2. DNS records configured? — Both MX and TXT records must be verified. Check with dig MX yourdomain.com and dig TXT yourdomain.com
  3. Domain verified? — Go to Domains and check that both MX and TXT show green checkmarks
  4. Inbox active? — Expired inboxes stop receiving. Check the TTL countdown
  5. Port forwarding? — If running behind a firewall, port 25 must be forwarded to 2525. See Reverse Proxy
  6. Redis running? — The SMTP router looks inboxes up in Redis first and falls back to Postgres on a miss, so Redis being down slows ingest rather than stopping it. GET /readyz covers the API process; smtpd exposes no HTTP endpoint, so check its logs.
bash
# Test SMTP directlyswaks --to test@yourdomain.com --server localhost:2525 # Check healthcurl http://localhost:8080/readyz

Domain Never Verifies

Symptoms: MX and/or TXT stay red on the domain detail page no matter how many times you click Re-verify DNS.

  1. Is BB_SMTP_HOSTNAME set on the API process? — The API, not smtpd, runs DNS verification. Setting it only on the SMTP container leaves the API on the localhost default, which no real MX record matches. Docker Compose sets it on both services for exactly this reason.
  2. Does the MX target match it exactly? — The comparison is case-insensitive equality with the trailing dot stripped; there is no suffix or subdomain fallback. An MX of mail.example.com against a BB_SMTP_HOSTNAME of example.com does not verify.
    bash
    dig +short MX yourdomain.com                     # must equal BB_SMTP_HOSTNAMEdocker compose exec api printenv BB_SMTP_HOSTNAME
  3. Is the TXT token current? — The value is burnerbyte-verify=<domain UUID>. Deleting and re-adding a domain mints a new one, so the old record stops matching.
  4. SPF stuck red? — SPF is informational and gates nothing, but the check needs a v=spf1 record containing BB_SMTP_HOSTNAME as a literal substring. "v=spf1 mx -all" is valid SPF and will still read red; use "v=spf1 a:mail.yourserver.com mx -all".
  5. Was it green and went red? — That is not a transient lookup failure: a lookup error preserves the previous status. Red after green means a successful lookup returned no match, so the record really did change.

WebSocket Not Connecting

Symptoms: Real-time updates don't work, inbox page shows "Disconnected".

  1. Reverse proxy configured for WebSocket? — Nginx needs proxy_http_version 1.1 and Upgrade headers. See Reverse Proxy
  2. CORS origins correct? — BB_CORS_ALLOWED_ORIGINS must include your frontend URL
  3. Auth failing? — The UI authenticates WebSockets with a short-lived one-time ticket: it calls POST /api/v1/ws/ticket and connects with ?ticket=<ticket>. A 401 on that POST means the access token has expired. Non-browser clients may still pass ?token=<jwt> directly.

Setup Wizard Loops

Symptoms: Redirected back to /setup after completing it.

The setup state is stored in the setup_state database table. If the table is empty or the completed flag is false:

sql
-- Check setup state (a singleton table — always exactly one row, id = true)SELECT * FROM setup_state; -- Force completion (if setup was done manually)UPDATE setup_state   SET completed = true,       completed_at = now() WHERE id = true;

Database Connection Errors

Symptoms: API returns 500 errors, /readyz fails.

  1. Connection string correct? — Check DATABASE_URL format: postgres://user:pass@host:5432/dbname?sslmode=disable
  2. Migrations applied? — Run make migrate-up
  3. Connection pool exhausted? — Increase BB_DATABASE_MAX_OPEN_CONNS (default: 25)

SSO Login Fails

Symptoms: "SSO login failed" error after redirect.

  1. Redirect URL matches? — The callback URL in your provider must exactly match the redirect_url configured in BurnerByte
  2. Client ID/Secret correct? — Use the Test button on the SSO provider card to verify connectivity
  3. Allowed domains? — If allowed_domains is set, the user's email domain must be in the list
  4. Encryption key set? — SSO secrets are encrypted at rest. Ensure BB_ENCRYPTION_KEY is a 64-character hex string
bash
# Generate an encryption keyopenssl rand -hex 32

Attachments Not Saving

Symptoms: Emails arrive but attachments are missing.

  1. Attachments enabled? — Check org settings (attachments_enabled) and domain assignment settings
  2. MinIO running? — Check GET /api/v1/admin/health for MinIO status
  3. Bucket exists? — BB_MINIO_BUCKET (default burnerbyte) is created automatically at boot, not on first upload. If creation fails — typically AccessDenied — the process falls back to local-filesystem attachments at /data/attachments. Check the startup logs.
  4. File size limit? — Check BB_DEFAULTS_MAX_ATTACHMENT_SIZE_MB (default: 25 MB)

Rate Limiting

Symptoms: 429 Too Many Requests errors.

Default limits:

  • Authenticated: 300 requests/minute
  • Unauthenticated: 60 requests/minute
  • Login: 10 attempts/minute per IP
  • Password reset: 3 requests/hour per IP

Note that .env.example ships 100 / 20 / 5 for the first three — if you copied it, those are your effective limits rather than the defaults above.

Adjust via config:

yaml
rate_limit:  authenticated: 200  unauthenticated: 50  login: 10

Account Lockout

Symptoms: "Account locked" error on login.

After 5 failed login attempts (configurable), the account is locked for 15 minutes. Wait for the lockout to expire, or have an admin unlock via the user detail dialog in Settings → Users.

Performance Issues

Symptoms: Slow page loads, high API latency.

  1. Check health endpoint — GET /api/v1/admin/health shows service latencies
  2. Database indexes — Ensure all 50 migrations are applied (74 indexes)
  3. Redis cache — Analytics and inbox routing are cached in Redis. Verify Redis is running
  4. Connection pool — Increase BB_DATABASE_MAX_OPEN_CONNS for high-traffic deployments
  5. Worker intervals — The analytics worker pre-computes stats every 5 minutes. Reduce BB_WORKERS_ANALYTICS_INTERVAL for fresher data

Getting Help