Troubleshooting — Diagnóstico de Problemas

Autorização

401 — Token Inválido

• Sintoma: API retorna "Missing authorization" ou o dashboard mostra "Unauthorized"
• Causas: Token ausente, expirado (TTL de 24 horas) ou formato incorreto do cabeçalho
• Solução: Faça login novamente. Para SSE/WebSocket, o token é passado via ?token=. JWT é renovado a cada 24 horas

401 — Email Não Verificado

• Sintoma: Login bem-sucedido, mas retorna requires_verification: true
• Causas: O link de verificação no email não foi clicado (TTL de 24 horas)
• Solução: Verifique o email e clique no link. Ou peça ao admin para verificar manualmente. Usuários OAuth são verificados automaticamente

403 — Sem Acesso ao Projeto

• Sintoma: Operações com arquivos ou terminal WebSocket retornam Forbidden
• Causas: Multi-tenancy — o usuário não é dono do projeto. Ou tentativa de path traversal foi bloqueada
• Solução: Verifique o ownership do projeto. O terminal interativo está disponível apenas para admin/CEO

Workers e Bots

Worker Não Responde

• Sintoma: Mensagem enviada, mas sem resposta
• Causas: Processo Claude ocupado, sessão tmux caiu, porta ocupada
• Diagnóstico: Verifique /health ou /ping no Telegram. No CRM — ícone de status ao lado do worker
• Solução: Clique em STOP e tente novamente. Ou reinicie via CRM Settings → Restart

Status: "degraded"

• Sintoma: Health check retorna status: "degraded" em vez de "ok"
• Causas: 3+ erros consecutivos do subprocess Claude
• Solução: Aguarde — o watchdog reiniciará automaticamente. Ou reinicie manualmente via /watchdog no Telegram

Timeout (5 minutos)

• Sintoma: Bot retorna "Claude timeout (5 min limit)"
• Causas: Tarefa complexa demais para uma única mensagem, arquivos muito grandes
• Solução: Divida a tarefa em etapas menores. Troque para um modelo mais rápido (Haiku)

Max turns reached

• Sintoma: "Reached max turns" — Claude parou após N passos
• Causas: A tarefa requer mais tool calls do que o limite (padrão: 20 para Developer, 10 para Consultant)
• Solução: Divida a tarefa. Ou aumente max_turns via Worker Studio

Watchdog desativou o bot

• Sintoma: "Permanently disabled after 10 consecutive failures"
• Causas: 10 falhas consecutivas (token ausente, arquivos removidos, porta ocupada)
• Solução: Corrija a causa raiz e reinicie via Master Bot /deploy ou CRM Restart

NotebookLM Bridge

Busca Semântica Não Funciona

• Sintoma: arc kb search ou aba NotebookLM retorna erro
• Diagnóstico: Verifique /health — se google_auth: true
• Causas: Autorização Google expirada, serviço bridge não está rodando
• Solução: Reinicie o serviço bridge. Atualize a autenticação Google

Dados Desatualizados na Busca

• Sintoma: A busca retorna informações antigas
• Causas: Cache (TTL de 5 minutos) ou fontes não sincronizadas
• Solução: Execute arc memory refresh para ressincronização completa

Fila de Sincronização Cheia (429)

• Sintoma: Sync retorna HTTP 429
• Causas: Mais de 200 elementos na fila
• Solução: Aguarde 2-3 minutos — a fila é processada na velocidade de 1 elemento / 2 segundos

Frontend e Conexões

WebSocket Desconecta

• Sintoma: Terminal ou chat desconecta com código 1008
• Causas: Token JWT expirou durante a sessão (TTL de 24 horas)
• Solução: Atualize a página (F5) — o token será renovado automaticamente

SSE Streaming Não Funciona

• Sintoma: A resposta do worker não aparece em tempo real
• Causas: Projeto não encontrado no registry, ou nginx buffering ativado
• Solução: Verifique o nome do projeto. SSE requer proxy_buffering off no nginx

Erro CORS

• Sintoma: Console do navegador mostra CORS blocked
• Causas: Origin não está na whitelist de CRM_ALLOWED_ORIGINS
• Solução: Adicione o origin à variável CRM_ALLOWED_ORIGINS e reinicie o Master Bot

Mensagem Cortada

• Sintoma: Resposta no Telegram é interrompida
• Causas: Limite de 4096 caracteres do Telegram
• Solução: O bot divide automaticamente em partes [1/3] [2/3] [3/3]. Se não fizer isso — é um bug na split logic

Banco de Dados

"Database not initialized"

• Sintoma: Bot cai com o erro "Database not initialized. Call initDb() first."
• Causas: initDb() não foi chamado antes da primeira requisição, ou o arquivo do DB foi removido
• Solução: Reinicie o Master Bot — ele inicializa o DB automaticamente e executa as migrations

"Database locked"

• Sintoma: Erros 500 aleatórios sob alta carga
• Causas: SQLite sendo escrito simultaneamente por múltiplos processos
• Solução: Modo WAL está ativado por padrão. Reinicie os processos travados

Referência Rápida

Comandos Úteis para Diagnóstico

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

# Verificar sessões tmux
tmux list-sessions

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

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

# Verificar portas
ss -tlnp | grep '192[0-9][0-9]'

# Estado do banco de dados
sqlite3 data/citadel.db "PRAGMA integrity_check;"

Doc enforcement (Phase 49.1+)

git push bloqueado com "doc-coverage check failed"

O pre-push hook exige atualização dos docs quando o código é alterado. O STDERR mostrará exatamente quais arquivos precisam ser atualizados.

Soluções rápidas:

• Auto-draft: arc wrapup --generate → preencha o TODO → commit
• Manual: veja o mapeamento em CLAUDE.md (Documentation Law)
• Bypass de emergência: git push --no-verify (deixa rastro no git log)

Hook não executa em um novo clone

bash scripts/setup-hooks.sh   # one-time per clone
git config core.hooksPath     # verifique se = ".githooks"

GitHub Integration (Phase 49.3)

Webhook retorna 401

• Content-Type: application/json no webhook do GitHub (não form-urlencoded)
• O secret deve corresponder ao output de arc github link
• Secret perdido → remova o webhook na UI do GitHub + arc github unlink, crie um novo

Feed GitHub na Sidebar está vazio

• ContextRail visível em viewport ≥1280px
• Hard refresh (Ctrl+Shift+R)
• Verificação no DB: sqlite3 data/citadel.db "SELECT COUNT(*) FROM github_events WHERE project_name='<name>';"

Rate limit "429 Rate limited"

Cap = 100 req/min/projeto. Aumente em shared/routes/github.ts:RATE_MAX.

Mais detalhes: GitHub Integration Setup.