Troubleshooting

Symptom	Likely cause
Process exits immediately	Missing .env, or a required variable empty/invalid. See Configuration.
UI returns 503	web/dist not built. Run npm run build:web in full mode.
/ is 404	ORDRYN_MODE=api: there is no web UI. Use full or call /api/v2 only.
Works on the server, connection refused from other machines	HOST defaults to 127.0.0.1. Set HOST=0.0.0.0, or put a reverse proxy in front.
API 401/403 or "API disabled"	REST not enabled. Admin UI, or ORDRYN_BOOTSTRAP_ENABLE_API=true, then restart.
Auth / rate limit failures, redis_ok: false	Redis down or REDIS_URL wrong. Redis is required for the API and live updates.
Other users' changes only appear after a reload	The SSE stream (/api/v2/events) is buffered or cut by the proxy, or Redis is down. See Reverse-proxy.
Attachment or image upload fails with 413	Proxy body limit. Raise nginx client_max_body_size. See Reverse-proxy.
No attach button on tasks	Attachments are off. Admin → Site settings → Allow file attachments on tasks.
Image paste or avatar upload fails	Image hosting is None, the Local directory isn't writable, or S3 credentials are wrong. See Admin-settings.
Search is slow on large sites	pg_trgm is missing. Check the startup log, then run CREATE EXTENSION pg_trgm; as a superuser and restart.
Cannot register	Invite-only is on. Use an invite, bootstrap an admin, or turn invite-only off in Admin.
JSON errors replaced with HTML	Reverse proxy proxy_intercept_errors / error_page rewriting API responses. See Reverse-proxy.
Assets 404 under a subpath	BASE_PATH does not match the public prefix, or SPA not rebuilt after changing it.
Old /app/... bookmarks	UI is at / (or BASE_PATH). Legacy /app/ redirects; update proxies that mount only /app.
Email, S3, or GitHub stopped after changing secrets	Rotated SESSION_KEY without re-entering the stored secrets in Admin.
Extension missing from Admin → Extensions	Folder not in EXTENSIONS_DIR, folder name ≠ manifest id, or invalid manifest. Check the log for extensions: failed …, then Reload Extensions.
Extension messages have no task link	PUBLIC_URL not set. See Configuration.
Extension stopped posting	Deliveries marked dead after 8 failures. Fix the webhook URL, then retry from the project's Extensions tab.
GitHub link fails with a redirect error	OAuth app callback URL must be https://<host><BASE_PATH>/api/v2/auth/github/callback, and the proxy must forward X-Forwarded-Proto.
Bootstrap key missing on later boots	The bootstrap key is printed once. Create a new key in Settings.
Admin Site version is dev, changelog empty	Binary was built without -ldflags (or systemd cwd is not the git checkout). Fetch tags, rebuild, restart. See Building-the-server.
Phone app cannot reach the server	Use the machine's LAN IP, not localhost on the device, and set HOST=0.0.0.0.

GET /api/v2/health is the first check: version, mode, api_enabled, redis_ok.