Troubleshooting
Problemas comuns ao rodar o ForgeRouter e como diagnosticar.
Todas as chamadas retornam 502/503
Geralmente significa que nenhum provedor configurado está saudável no momento. Verifique:
curl http://localhost:2100/v1/modelsSe a lista vier vazia, revise as chaves de API em config/providers.yaml — uma chave inválida
faz o health check daquele provedor falhar silenciosamente.
model_used sempre aponta pro provedor de fallback
Indica que o provedor de prioridade 1 está com health check falhando. Confira os logs do
container (docker compose logs forgerouter) pela mensagem de erro específica daquele provedor
— timeout, 401 (chave inválida) e 429 (rate limit) têm tratamentos diferentes.
Streaming não funciona atrás do meu proxy reverso
Proxies reversos com buffering ligado por padrão (comum em configurações genéricas de Nginx)
seguram a resposta SSE inteira antes de repassar. Desative o buffering especificamente na rota
do ForgeRouter (proxy_buffering off; no Nginx, ou equivalente no seu proxy).
Onde ver logs
docker compose logs -f forgerouterSe o problema persistir depois desse checklist, vale uma conversa — às vezes é uma configuração de rede específica do seu ambiente que não tem como prever numa doc genérica.