Troubleshooting Common Failures
Purpose: provide strict symptom-to-cause-to-fix guidance for common integration failures.
Failure Matrix
| Symptom | Likely Cause | Fix |
|---|---|---|
POST /query returns 401 (Missing bearer token) | Authorization header missing | Send Authorization: Bearer <token> from auth bootstrap flow |
POST /query returns 401 (Invalid token) | Expired/invalid JWT or wrong issuer/audience | Re-bootstrap token and confirm auth config (AUTH_ISSUER, AUTH_AUDIENCE, JWKS URL) |
POST /query returns 400 (start_ts must be <= end_ts) | Invalid time range in request body | Ensure start_ts is less than or equal to end_ts |
POST /log returns 400/validation error | Request body is not valid JSON object | Always send JSON body (minimum {}) |
Private channel write returns 401 | No token supplied for owner-protected channel | Send valid owner Bearer token |
Private channel read/write returns 404 | Account mismatch with channel owner | Use token with matching JWT acc claim |
WebSocket private upgrade returns 401 | Missing/invalid token in upgrade request | Include valid Authorization header during upgrade |
WebSocket private upgrade returns 404 | Token acc does not match channel owner | Reconnect with owner-account token |
POST /query returns empty files | No uploaded files in range or filters too narrow | Expand range/filter values and verify uploader/compression workers are running |
/query endpoints missing from OpenAPI | Database integration disabled | Set DATABASE_URL and restart service to enable query routes |
Quick Diagnostics
JSONLOG_BASE_URL="http://localhost:3002"
curl -sS "${JSONLOG_BASE_URL}/health"
curl -sS "${JSONLOG_BASE_URL}/stats"
curl -sS "${JSONLOG_BASE_URL}/openapi.json" | jq '.paths | keys'Scripted Auth Troubleshooting
cd jsonlog
set -a && source .env && set +a
npm run test:auth:smokeThis smoke flow validates missing-auth, invalid-auth, and valid-auth behavior for /query.