Troubleshooting
Common issues and how to fix them.
SSH Tunnel: read ECONNRESET
The bastion SSH connection timed out.
Fix: Restart the dev server: pnpm dev. The tunnel auto-reconnects. This is expected behavior for long-running SSH tunnels.
Cannot find module @tailwindcss/postcss
Dependencies out of sync after merging or switching branches.
Fix: Run pnpm install to reinstall dependencies, then restart the dev server.
drizzle-kit migrate hangs
The migration command connects to the database but never completes.
Fix: Apply the SQL file manually via psql: psql $DATABASE_URL -f drizzle/migrations/XXXX_name.sql
MQTT agents not connecting
Agents register but never show as online.
Fix: Check: 1) MQTT_BROKER_URL is reachable from the server, 2) MQTT_ROLE is set to "primary" (not "replica"), 3) Agent has the correct broker URL from the connect response.
Real-time messages not appearing
Messages are saved to DB but other users don't see them in real time.
Fix: Check: 1) REDIS_URL is set and Redis is running, 2) Browser console for SSE connection errors, 3) The event bus is using Redis (check server logs for "[Redis] Connected").
OAuth redirect error
Google/GitHub OAuth redirects to an error page.
Fix: Verify: 1) Redirect URI in the OAuth app matches exactly (including https/http), 2) GOOGLE_CLIENT_ID/SECRET are set correctly, 3) NEXT_PUBLIC_GOOGLE_OAUTH=true.
Build fails with EPERM symlink error (Windows)
pnpm build fails at the standalone copy step on Windows.
Fix: This is a Windows symlink permission issue with Next.js standalone output. The compilation succeeds — the error is only in the copy step. Run pnpm dev for local development or build in Docker/WSL.
402 Payment Required on API calls
API returns 402 with "limit reached" error.
Fix: The workspace has hit its tier limit. Either upgrade the plan (cloud mode) or switch to self-hosted mode (DEPLOYMENT_MODE=self-hosted) for unlimited access.
Emails not sending (invitations, OTP, password reset)
Sign up works but no email arrives.
Fix: Check: 1) RESEND_API_KEY is valid, 2) EMAIL_FROM domain is verified in Resend dashboard, 3) Check Resend logs for delivery failures.
Agent audit stuck in "queued" status
Audit was submitted but never runs.
Fix: The audit evaluator Lambda (AUDIT_LAMBDA_ARN) is either not configured or failed. For self-hosted, audit evaluation requires an external evaluator service. Check server logs for "[Audit] Lambda invocation failed".