Troubleshooting
| Problem | Fix |
|---|---|
UI not on :3001 | npm run dev:ui (or npm run docker:full) |
Docs not on :3003 | npm run dev:docs (or full Docker profile) |
AuthenticationError / AUTH_FAILED on send | Invalid platform bot_token / credentials |
| Bot not responding in Telegram | Add bot to group; confirm target_chat_id |
| Can’t log into Admin UI | Complete /setup or reset admin_users |
/setup redirects to /login | Admin already exists — log in or delete admin_users row |
| API returns 401 | Set X-API-Key with a valid scoped key; ensure USE_AUTH=true if expected |
| API returns 403 | Key lacks required scope — use admin key or grant the scope via Settings |
| Prompt not delivered | Check channel type is PROMPT; inspect core logs |
| Callbacks never arrive | Public callback_url; verify signing; check retry / offline notification |
| WhatsApp / Messenger options rejected | Max 3 button options on those platforms |
Cannot find module './vendor-chunks/…' in docs | rm -rf docs-site/.next and restart |
| Docker not running | Start Docker Desktop, then npm run infra:up |
| Port 5432 in use | Set POSTGRES_PORT and match DATABASE_URL |
| UI container unhealthy / Traefik cannot reach UI | Set HOSTNAME=0.0.0.0; map Dokploy domain to port 3000; verify curl http://127.0.0.1:3000/api/health returns 200 inside container |
Logs
# Hybrid — app logs are in the terminal running npm run dev
docker compose logs -f postgres
# Full Docker
npm run docker:logsHealth
curl http://localhost:8100/healthz
curl http://localhost:3001/api/health # Admin UI (hybrid dev port)
curl -H "X-API-Key: $GREENLIGHT_API_KEY" \
http://localhost:8100/v1/statusSelf-host containers probe http://127.0.0.1:3000/api/health (UI) and http://127.0.0.1:8100/healthz (API) internally. Do not use /wh/healthz when API is routed under /wh.