Troubleshooting Matrix
Practical field diagnostic steps for symptoms encountered during development, testing, and production operations.
3 min read
•Production Verified
Diagnostic Matrix
| Symptom | Likely Cause | Remediation |
|---|---|---|
| Rollback failed (402 VERCEL_PLAN_LIMIT) | Vercel Hobby plan rejects rollbacks older than 1 release. | Ensure the atomic promote fallback is active in packages/core/src/adapters/vercel.ts line 330. |
| Decryption failed: Unsupported state | ENCRYPTION_KEY in .env does not match key used when encrypting. | Revert ENCRYPTION_KEY or execute npm run ops:reencrypt to migrate keys. |
| Neon timeout / Pool exhausted | Using direct unpooled URL in serverless functions. | Ensure DATABASE_URL points to Neon's pooler endpoint with sslmode=require. |
| MCP Tool returns 401 Unauthorized | Missing or invalid Bearer key hash in mcp_api_keys table. | Generate a new API key in Settings (fb_mcp_...) and supply it in headers. |
| Probe blocked: SSRF_BLOCKED | Health URL resolved to localhost or private RFC 1918 subnet. | Firebreak's SSRF guard blocks internal IPs. Use a public URL or ngrok tunnel. |