Diagnóstico De Fallos Comunes
Objetivo: ofrecer una guía estricta de síntoma-causa-corrección para fallos frecuentes de integración.
Matriz De Fallos
| Síntoma | Causa probable | Corrección |
|---|---|---|
POST /query devuelve 401 (Missing bearer token) | Falta el header de autorización | Envía Authorization: Bearer <token> desde el flujo de inicialización de auth |
POST /query devuelve 401 (Invalid token) | JWT expirado/inválido o issuer/audience incorrecto | Regenera token y confirma configuración auth (AUTH_ISSUER, AUTH_AUDIENCE, URL JWKS) |
POST /query devuelve 400 (start_ts must be <= end_ts) | Rango temporal inválido en el cuerpo | Asegura que start_ts sea menor o igual que end_ts |
POST /log devuelve 400/error de validación | El cuerpo no es un objeto JSON válido | Envía siempre cuerpo JSON (mínimo {}) |
Escritura en canal privado devuelve 401 | No se envió token para canal protegido | Envía token Bearer válido del propietario |
Lectura/escritura en canal privado devuelve 404 | La cuenta no coincide con el propietario del canal | Usa un token con claim acc coincidente |
Upgrade WebSocket privado devuelve 401 | Token faltante/inválido en el upgrade | Incluye header Authorization válido durante el upgrade |
Upgrade WebSocket privado devuelve 404 | acc del token no coincide con el propietario | Reconecta con token de la cuenta propietaria |
POST /query devuelve files vacío | No hay archivos en rango o filtros muy estrechos | Amplía rango/filtros y verifica que uploader/workers de compresión estén ejecutándose |
Endpoints /query ausentes en OpenAPI | Integración con base de datos deshabilitada | Define DATABASE_URL y reinicia el servicio para habilitar rutas de consulta |
Diagnóstico Rápido
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'Diagnóstico De Auth Con Script
cd jsonlog
set -a && source .env && set +a
npm run test:auth:smokeEste flujo smoke valida comportamientos sin auth, con auth inválida y con auth válida para /query.