Problemas comuns, suas causas e soluções. Referência rápida para quando algo dá errado.
O que é: O repositório original do MiroFish tem funções faltando em config.py que causam ImportError na inicialização do backend. O fork inematds corrigiu isso.
Por que aprender: Se você clonou o repositório errado (original em vez do fork), este é o primeiro erro que vai encontrar. A solução é usar o fork.
# Erro típico:
ImportError: cannot import name 'get_llm_config' from 'config'
AttributeError: module 'config' has no attribute 'get_graph_db_path'
# Causa:
O original não tem as funções que outros módulos importam.
config.py original é incompleto.
# Solução:
# Use o fork inematds (já corrigido):
git clone https://github.com/inematds/mirofish.git
# Ou consulte MIGRATION-GUIDE.md para as
# funções que precisam ser adicionadas.
O que é: Claude CLI falha quando o prompt é passado como argumento de linha de comando e excede o limite do OS (ARG_MAX ~2MB no Linux). A solução é usar stdin.
Por que aprender: Este bug só aparece em simulações reais com contexto rico. É um dos problemas mais frustrantes porque a mensagem de erro não é clara.
# Erro típico:
OSError: [Errno 7] Argument list too long: 'claude'
# ou simplesmente: exit code 1 sem mensagem
# Causa:
claude --print "prompt muito longo aqui..."
# O prompt excede o limite de argumentos do shell
# Solução (já implementada no fork):
# Em vez de passar como argumento:
❌ subprocess.run(["claude", "--print", prompt])
# Passar via stdin:
✅ subprocess.run(["claude", "--print", "-"],
input=prompt, text=True)
O que é: Simulações podem ser lentas (horas) ou caras ($100+) se mal dimensionadas. As principais causas são muitas rodadas, muitos agentes ou modelo LLM caro demais.
Por que aprender: Otimizar a relação custo/qualidade é essencial para uso prático. Nem sempre mais rodadas = melhores resultados.
# Estratégias de otimização:
1. Limitar rodadas (< 40 para testes, < 100 para produção)
2. Usar LLM mais barato para simulação (LLM_BOOST)
3. Reduzir número de agentes (10-20 é suficiente para testes)
4. Usar Claude CLI para testes ($0)
# Tabela de referência de tempo:
10 agentes × 10 rodadas (Claude CLI): ~5 min
20 agentes × 20 rodadas (GPT-4o-mini): ~15 min
50 agentes × 50 rodadas (GPT-4o): ~2 horas
100 agentes × 100 rodadas (qualquer): ~8+ horas
# Dica: comece com 5 agentes, 5 rodadas
# Valide que funciona, depois escale gradualmente.
O que é: Dentro do Docker, o Claude CLI não consegue acessar suas credenciais a menos que os diretórios de configuração sejam montados como volumes.
Por que aprender: Este é o problema #1 reportado por usuários que fazem deploy com Docker + Claude CLI. A mensagem de erro é "not authenticated".
# Erro típico:
Error: Not authenticated. Please run 'claude' to authenticate.
# Causa:
O container Docker não tem acesso aos arquivos de
autenticação do Claude CLI que ficam no host.
# Solução - adicionar volumes no docker-compose.yml:
volumes:
- ~/.claude:/root/.claude:ro
- ~/.local/share/claude:/root/.local/share/claude:ro
# Verificar dentro do container:
docker compose exec app ls -la /root/.claude/
docker compose exec app claude --version
# Dica: :ro = read-only (mais seguro)
O que é: O código original tinha dependências circulares entre módulos Python (build_graph.py importava config.py que importava build_graph.py), causando ImportError.
Por que aprender: Importação circular é um erro Python clássico. A técnica de lazy import (mover o import para dentro da função) é a solução padrão.
# Erro típico:
ImportError: cannot import name 'build_graph' from
partially initialized module 'backend.build_graph'
(most likely due to a circular import)
# Código original (problema):
❌ # No topo do arquivo
from build_graph import process_documents
# Código corrigido no fork (lazy import):
✅ def some_function():
# Import dentro da função (lazy)
from build_graph import process_documents
return process_documents(data)
# O import só acontece quando a função é chamada,
# quebrando o ciclo de dependência.
O que é: Tabela de referência rápida com os problemas mais frequentes, suas causas e soluções. Consulte antes de abrir uma issue no GitHub.
Por que aprender: 95% dos problemas reportados são os mesmos. Esta tabela resolve a maioria sem precisar de ajuda externa.
# Tabela: Problema → Causa → Solução
┌──────────────────────────────────────────────────────┐
│ PROBLEMA │ CAUSA │ SOLUÇÃO │
├──────────────────────────────────────────────────────┤
│ ModuleNotFoundError │ Python 3.13+ │ Use 3.11/3.12 │
│ npm setup:all falha │ uv ausente │ Instalar uv │
│ Backend não inicia │ .env faltando│ cp .env.example │
│ "Not authenticated" │ Docker s/vol │ Montar ~/.claude│
│ Porta 5001 em uso │ Outro proc. │ lsof -i :5001 │
│ ENOMEM / killed │ Pouca RAM │ Usar ≥8GB │
│ Arg list too long │ Prompt grande│ Usar stdin │
│ Circular import │ Bug original │ Usar fork │
│ OASIS incompatível │ API não-OAI │ Usar LLM_BOOST │
│ Simulação sem fim │ Muitas rodadas│ Limitar < 40 │
│ Relatório vazio │ LLM timeout │ Verificar logs │
│ SSL não funciona │ acme.json │ chmod 600 │
└──────────────────────────────────────────────────────┘
# Comandos de diagnóstico rápido:
python --version # Deve ser 3.11 ou 3.12
node --version # Deve ser 18+
cat .env | grep PROVIDER # Deve ter LLM_PROVIDER
docker compose ps # Deve mostrar "Up"
docker compose logs --tail=50 app # Últimos erros