Troubleshooting — Diagnóstico de problemas

Autorización

401 — Token inválido

• Síntoma: La API devuelve "Missing authorization" o el dashboard muestra "Unauthorized"
• Causas: Token ausente, caducado (TTL 24 horas) o formato de cabecera incorrecto
• Solución: Vuelve a iniciar sesión. Para SSE/WebSocket el token se pasa mediante ?token=. El JWT se renueva cada 24 horas

401 — Email no verificado

• Síntoma: El login es exitoso, pero devuelve requires_verification: true
• Causas: No se hizo clic en el enlace del correo de verificación (TTL 24 horas)
• Solución: Revisa el email y haz clic en el enlace. O pide al administrador que lo verifique manualmente. Los usuarios de OAuth se verifican automáticamente

403 — Sin acceso al proyecto

• Síntoma: Las operaciones con archivos o el terminal WebSocket devuelven Forbidden
• Causas: Multi-tenancy — el usuario no es el propietario del proyecto. O bien se bloqueó un intento de path traversal
• Solución: Verifica la propiedad del proyecto. El terminal interactivo solo está disponible para admin/CEO

Workers y bots

El worker no responde

• Síntoma: Se envió el mensaje pero no hay respuesta
• Causas: Proceso Claude ocupado, sesión tmux caída, puerto en uso
• Diagnóstico: Comprueba /health o /ping en Telegram. En el CRM — el icono de estado junto al worker
• Solución: Haz clic en STOP y vuelve a intentarlo. O reinicia desde CRM Settings → Restart

Estado: "degraded"

• Síntoma: El health check devuelve status: "degraded" en lugar de "ok"
• Causas: 3+ errores consecutivos del subprocess Claude
• Solución: Espera — el watchdog reiniciará automáticamente. O reinicia manualmente con /watchdog en Telegram

Timeout (5 minutos)

• Síntoma: El bot devuelve "Claude timeout (5 min limit)"
• Causas: La tarea es demasiado compleja para un solo mensaje, archivos muy grandes
• Solución: Divide la tarea en pasos más pequeños. Cambia al modelo más rápido (Haiku)

Max turns reached

• Síntoma: "Reached max turns" — Claude se detuvo después de N pasos
• Causas: La tarea requiere más llamadas a herramientas de las permitidas (por defecto 20 para Developer, 10 para Consultant)
• Solución: Divide la tarea. O aumenta max_turns desde Worker Studio

Watchdog deshabilitó el bot

• Síntoma: "Permanently disabled after 10 consecutive failures"
• Causas: 10 fallos consecutivos (token ausente, archivos eliminados, puerto en uso)
• Solución: Corrige la causa raíz y luego reinicia con el Master Bot /deploy o CRM Restart

NotebookLM Bridge

La búsqueda semántica no funciona

• Síntoma: arc kb search o la pestaña NotebookLM devuelve un error
• Diagnóstico: Comprueba /health — si google_auth: true
• Causas: La autorización de Google caducó, el servicio Bridge no está iniciado
• Solución: Reinicia el servicio Bridge. Actualiza la autenticación de Google

Datos obsoletos en la búsqueda

• Síntoma: La búsqueda devuelve información desactualizada
• Causas: Caché (TTL 5 minutos) o fuentes no sincronizadas
• Solución: Ejecuta arc memory refresh para una resincronización completa

Cola de sincronización desbordada (429)

• Síntoma: Sync devuelve HTTP 429
• Causas: Más de 200 elementos en la cola
• Solución: Espera 2-3 minutos — la cola se procesa a 1 elemento / 2 segundos

Frontend y conexiones

WebSocket se desconecta

• Síntoma: El terminal o el chat se desconecta con código 1008
• Causas: El token JWT caducó durante la sesión (TTL 24 horas)
• Solución: Recarga la página (F5) — el token se renovará automáticamente

El streaming SSE no funciona

• Síntoma: La respuesta del worker no aparece en tiempo real
• Causas: El proyecto no se encuentra en el registro, o el buffering de nginx está activado
• Solución: Verifica el nombre del proyecto. SSE requiere proxy_buffering off en nginx

Error CORS

• Síntoma: La consola del navegador muestra CORS blocked
• Causas: El origin no está en la lista blanca de CRM_ALLOWED_ORIGINS
• Solución: Añade el origin a la variable CRM_ALLOWED_ORIGINS y reinicia el Master Bot

El mensaje se trunca

• Síntoma: La respuesta en Telegram se corta
• Causas: Límite de Telegram de 4.096 caracteres
• Solución: El bot divide automáticamente en partes [1/3] [2/3] [3/3]. Si no lo hace — hay un bug en la lógica de división

Base de datos

"Database not initialized"

• Síntoma: El bot falla con el error "Database not initialized. Call initDb() first."
• Causas: initDb() no se llamó antes de la primera solicitud, o el archivo DB fue eliminado
• Solución: Reinicia el Master Bot — inicializará automáticamente la DB y ejecutará las migraciones

"Database locked"

• Síntoma: Errores 500 aleatorios con carga alta
• Causas: SQLite se escribe simultáneamente desde varios procesos
• Solución: El modo WAL está activado por defecto. Reinicia los procesos obsoletos

Referencia rápida

Comandos útiles para el diagnóstico

# Health checks
curl -s http://localhost:19210/api/master/health | jq .
curl -s http://localhost:19211/api/child/health | jq .

# Comprobar sesiones tmux
tmux list-sessions

# Logs del Master Bot
tmux capture-pane -t citadel-master -p | tail -20

# Logs del Child Bot
tmux capture-pane -t ws-arc-v2 -p | tail -20

# Comprobar puertos
ss -tlnp | grep '192[0-9][0-9]'

# Estado de la base de datos
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Doc enforcement (Phase 49.1+)

git push bloqueado con "doc-coverage check failed"

El pre-push hook requiere actualizar los docs cuando se cambia el código. STDERR mostrará qué archivos exactamente hay que actualizar.

Soluciones rápidas:

• Auto-borrador: arc wrapup --generate → completar TODOs → commit
• Manual: ver el mapeo en CLAUDE.md (Documentation Law)
• Bypass de emergencia: git push --no-verify (deja rastro en el git log)

El hook no se activa en un nuevo clone

bash scripts/setup-hooks.sh   # una sola vez por clone
git config core.hooksPath     # verifica que sea = ".githooks"

GitHub Integration (Phase 49.3)

El webhook devuelve 401

• Content-Type: application/json en el webhook de GitHub (no form-urlencoded)
• El secret debe coincidir con la salida de arc github link
• ¿Perdiste el secret? Elimina el webhook en la UI de GitHub + arc github unlink, crea uno nuevo

El feed de GitHub en la Sidebar está vacío

• ContextRail visible con viewport ≥1280px
• Hard refresh (Ctrl+Shift+R)
• Comprobación en la DB: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate limit "429 Rate limited"

El tope es de 100 req/min/proyecto. Auméntalo en shared/routes/github.ts:RATE_MAX.

Más detalles: Configuración de la integración con GitHub.