No meio de uma resposta longa, o CLI para de escrever e devolve:
API Error: Stream idle timeout - partial response receivedA sessão continua aberta e o histórico não se perde, mas o turno acabou ali. O erro nasce no próprio CLI, não na sua conta: um watchdog de stream abandonou a resposta porque os bytes pararam de chegar por tempo demais. Ele aparece em situações diferentes, com correções diferentes, e este guia separa cada uma.
O que significa "Stream idle timeout - partial response received"?
Significa que a resposta começou e foi cortada no meio. Os primeiros bytes chegaram, o stream abriu, e em algum ponto entre um chunk e o próximo a conexão ficou muda até o watchdog estourar e abortar o turno.
É diferente de No response from API, que é a espera antes do primeiro byte. Aqui a resposta já estava em andamento. O que se perde é o trecho que estava sendo gerado, não a conversa: a sua mensagem, os arquivos lidos e as ferramentas já executadas seguem na sessão.
Por que a resposta corta no meio?
Três causas respondem por quase todos os relatos, e cada uma pede uma correção diferente. Antes de mexer em configuração, identifique a sua.
| Causa | Como você reconhece | O que resolve |
|---|---|---|
| Silêncio do provedor ou do caminho até ele | corta em turnos longos, às vezes em todos | subir o limiar do watchdog |
| Proxy ou gateway que bufferiza a resposta | corta sempre atrás de VPN, gateway ou ANTHROPIC_BASE_URL | testar sem proxy e ajustar o prazo do retry |
| Latch de keep-alive do próprio CLI | a sessão piora com o tempo e reiniciar resolve | reiniciar a sessão ou voltar de versão |
Aumentei API_TIMEOUT_MS e nada mudou. Por quê?
Porque API_TIMEOUT_MS não é o teto da resposta em streaming. O próprio changelog descreve o comportamento: quando a API não manda cabeçalhos, o retry passa a esperar até API_TIMEOUT_MS, que vale 10 minutos por padrão. É um prazo de espera por resposta, não um relógio que mede o silêncio entre um chunk e o próximo.
Quem olha a mensagem de idle timeout e sobe esse número continua batendo no mesmo watchdog, porque o relógio que estourou é outro.
Qual variável controla o watchdog do stream?
É CLAUDE_STREAM_IDLE_TIMEOUT_MS, que configura o limiar do watchdog de idle do streaming e vem com 90 segundos por padrão. Quando nenhum byte chega dentro dessa janela, o turno é abortado e você vê a mensagem de partial response.
| Variável | O que controla | Padrão |
|---|---|---|
CLAUDE_STREAM_IDLE_TIMEOUT_MS | limiar do watchdog de idle do stream | 90 segundos |
API_TIMEOUT_MS | quanto o retry espera por uma resposta sem cabeçalhos | 10 minutos |
API_FORCE_IDLE_TIMEOUT | timeout de idle de 5 minutos restaurado por padrão no Vertex e no Foundry | ativo nesses provedores; 0 desativa |
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK | desliga o fallback não streaming quando o streaming falha | desligado |
Repare no escopo de cada uma: CLAUDE_STREAM_IDLE_TIMEOUT_MS é o watchdog genérico de silêncio no stream, enquanto API_FORCE_IDLE_TIMEOUT mexe num timeout específico de Vertex e Foundry. Se você não está nesses dois provedores, essa segunda variável não é a sua alavanca.
Para uma sessão, exporte antes de abrir o CLI. O valor é em milissegundos, então 180000 equivale a três minutos:
export CLAUDE_STREAM_IDLE_TIMEOUT_MS=180000
claudePara valer em todas as sessões, use o bloco env do ~/.claude/settings.json:
{
"env": {
"CLAUDE_STREAM_IDLE_TIMEOUT_MS": "180000"
}
}No PowerShell, a sintaxe é $env:CLAUDE_STREAM_IDLE_TIMEOUT_MS = "180000". Depois de salvar o arquivo, rode /status e confira a linha Setting sources para saber se o CLI carregou o arquivo.
Atenção: subir o limiar evita o aborto prematuro, não conserta uma conexão que caiu. Se o corte vem sempre no mesmo ponto, com o relógio batendo perto de um número redondo, o problema está no caminho da rede, não no prazo.
Por que sessão longa piora com o tempo?
Existe um agravante no pool de conexões. O changelog registra a mudança: o keep-alive passa a ser desligado depois de uma conexão obsoleta, para o retry abrir um socket novo. Segundo o relato da issue #100353, o código desliga essa chave e nada a religa: o processo passa a abrir conexão nova a cada requisição até ser reiniciado.
O autor mediu o efeito numa sessão de orquestrador com muitos subagentes, no Linux, com o watchdog em 60 segundos:
| Cenário | Requisições | Aborts do watchdog | Lacunas de 40 segundos ou mais | Erros 400 de continuação |
|---|---|---|---|---|
| Com o latch ativo | ~1.725 | 131 (7,6%) | 66 | 101 |
| Com o latch desativado no binário | ~2.190 | 0 | 0 | 2 |
Os números são do relato, não de uma medição nossa, e a issue segue aberta. O sinal está no log: rode com --debug-file e procure a linha que começa com Stale connection e termina com disabling keep-alive for retry. Depois dela, a sessão tende a piorar até reiniciar.
Como resolver quando só reiniciar resolve?
Se o log mostra o latch, as saídas são três, em ordem de custo:
- Reinicie a sessão longa depois do primeiro aviso. É o que o autor da issue faz, e o que derruba a taxa de stalls para zero.
- Rode uma versão do CLI anterior à mudança de keep-alive descrita na issue, onde o gatilho ainda não estava ativo.
- Se precisar ficar na versão atual, desligue o fallback não streaming, que é o que transforma um stall em reenvio da conversa inteira:
export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1
O item 3 não corrige o latch. Ele evita o efeito caro, que é reenviar de 0,35 a 1,1 MB de conversa a cada stall, segundo o mesmo relato.
O erro aparece em requisições de mais de 5 minutos?
Aí o limite é de outra natureza. Um relato aberto em 04/11/2026 com o CLI 2.1.317, atualizado em 07/11/2026, descreve o uso de um modelo local grande servido via ANTHROPIC_BASE_URL: qualquer requisição que passe de 5 minutos é abortada, com uma sequência de Request timed out. Retrying até o limite de tentativas.
Nesse cenário, o watchdog de stream não é o único envolvido, e o próprio autor aponta a possibilidade de um timeout de idle da camada HTTP do runtime. Para um modelo local que demora mais de 5 minutos por resposta, a saída prática é dividir a tarefa em pedaços menores ou esperar a correção, não aumentar variável de watchdog.
Como reduzir a chance de acontecer de novo?
- Divida turnos longos. Pedir um plano enorme num único turno é um dos cenários que aparecem nos relatos.
- Rode
/compactantes de tarefas longas, para o turno seguinte ter menos contexto para sustentar. - Teste sem VPN, proxy ou gateway quando o erro for constante, e compare com a API direta.
- Em automação, prefira sessões curtas e headless, reiniciando entre lotes.
- Abra sessões longas com
--debug-file, para ver o latch antes de perder a tarde.
A Verboo Code é a segunda rota para quando a primeira trava no meio: ela roda no mesmo fluxo de terminal e entrega tokens ilimitados, então um turno longo não esbarra em cota enquanto você investiga o stream. Manter dois caminhos configurados evita que um provider único pare o dia.
