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
Busca semântica / RAG (Phase 71)
arc kb search retorna resultado vazio para projeto recém-criado
- Sintoma: projeto novo sem wiki/issues — a busca retorna
No content found... - Causa: os RAG hooks (Phase 71.5) re-embedam o conteúdo na escrita, mas antes das primeiras gravações o índice está vazio. O fallback do CLI para keyword search na wiki/tree também não encontra nada.
- Solução: escreva algo em um wiki/issue/skill — o embedding entra em 1-2 segundos. Ou force via
arc memory refresh(re-embed do MANIFEST + ROADMAP + todos os arquivos de wiki).
Cohere 401 Unauthorized
- Sintoma: nos logs do master,
[rag-hook] ... failed: Cohere auth rejected (401) - Causa: a
COHERE_API_KEYno vault expirou ou foi rotacionada incorretamente. - Solução:
Platform Settings → RAG / Semantic search → Rotate. O botão liveTestvalida a nova chave via/v2/embed.
Cohere 429 Rate Limited
- Sintoma: backfill ou hooks falham com 429.
- Causa: a chave Cohere do tier Trial tem cap de 1000 calls/mês; em produção é preciso o tier Production.
- Solução: faça o upgrade em https://dashboard.cohere.com/billing. O primeiro backfill de produção em 2026-06-05 quebrou exatamente nisso — após a migração para Production, o ciclo de 178 docs passou com 0/178 erros.
Cauda de latência >500ms
- Sintoma: algumas consultas de busca retornam devagar.
- Causa: variância de cauda upstream da Cohere — nossa p50 é ~195ms em regime estável, mas chamadas individuais de
/v2/embedpodem levar 800-1000ms. - Solução: confira
docs/architecture/PHASE_71_SOAK_2026-06-05.md— é uma limitação upstream documentada, não do nosso código. Fases futuras: cache LRU de query-embed, region pinning da Cohere.
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 offno 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
| Problema | Primeiro a verificar | Solução Rápida |
|---|---|---|
| Bot não responde | /health ou /ping |
Restart via CRM |
| 401 Unauthorized | Hora de criação do token | Faça login novamente |
| 403 Forbidden | Ownership do projeto | Verificar owner_id |
| Degraded status | consecutiveFailures |
Aguardar watchdog |
| Timeout 5m | Complexidade da tarefa | Dividir em etapas menores |
| Erro do bridge | google_auth em /health |
arc memory refresh |
| CORS blocked | CRM_ALLOWED_ORIGINS | Adicionar origin |
| WebSocket disconnect | Tempo de vida do JWT (24h) | Atualizar a página |
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/jsonno webhook do GitHub (nãoform-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.