Claude Code «Stream idle timeout – no chunks received»: qué variable subir y qué no funciona (probado)

Respuesta corta: API Error: Stream idle timeout - no chunks received no es un error de los servidores de Anthropic. Es el propio watchdog de Claude Code cortando una respuesta en streaming que se quedó en silencio. Sube CLAUDE_STREAM_IDLE_TIMEOUT_MS; si no sabes cuánto dura tu pausa más larga, empieza con 1800000 (30 minutos), el valor inicial de la documentación de Anthropic sobre Claude apps gateway (pensada para despliegues con gateway). Probé los temporizadores contra un servidor simulado que se queda en silencio. Dos cosas me sorprendieron: los valores por debajo de 300000 se elevan en silencio a 300 segundos, y el texto exacto que vi en Claude Code 2.1.312 y 2.1.319 era distinto del documentado. Los detalles y registros están abajo.

Qué significa el error

Claude Code recibe la respuesta del modelo en streaming. Para no quedarse colgado para siempre en una conexión muerta, ejecuta temporizadores que abortan un flujo que deja de entregar datos. Según la documentación de configuración de red de Anthropic, hay cuatro:

Temporizador	Aborta cuando	Valor por defecto
—	—	—
Plazo del primer byte	No llegan cabeceras de respuesta tras enviar la petición (API directa y algunas otras conexiones)	180 s en la API directa de Anthropic
Watchdog por eventos	No se puede analizar ningún evento de respuesta	300 s
Watchdog por bytes	No llega ningún byte, ni siquiera pings	180 s en la API directa; 300 s con un ANTHROPIC_BASE_URL personalizado
Tiempo de inactividad del cuerpo	Ningún byte durante 5 minutos (en proveedores distintos de la API directa)	5 minutos

El texto de error documentado para este caso es API Error: Stream idle timeout - no chunks received, que aparece en la referencia de errores de Anthropic. La causa típica según la documentación es una pasarela o proxy en el camino: solo fluyen pings de mantenimiento mientras el modelo piensa mucho tiempo.

Lo que vi al dejar un flujo en silencio (probado)

Escribí un pequeño servidor simulado que responde a una petición de Claude Code con HTTP 200, envía el evento inicial message_start y luego no dice nada. Ejecuté claude -p "say hi" contra él, con ANTHROPIC_BASE_URL apuntando al simulado y una clave de API inventada:

Ajuste	Qué pasó
—	—
CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS=10000	Segunda petición exactamente 10 s después de la primera; salida final API Error: stream idle: no bytes for 10000ms (2.1.312 y 2.1.319)
Igual, pero el simulado envió antes algo de texto	Mismo resultado: reintento a los 10 s y luego el mismo API Error: stream idle: no bytes for 10000ms en modo -p
CLAUDE_ENABLE_BYTE_WATCHDOG=0 y CLAUDE_STREAM_IDLE_TIMEOUT_MS=10000	Sin fallo a los 10 s. Una petición nueva cada 300 s; tras dos intentos (600 s) terminó con Request timed out
CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS=15000 solo en el .claude/settings.json del proyecto, dentro de env	Reintento exactamente 15 s después, así que la vía del archivo de ajustes funciona

Tres notas honestas. Primera: no reproduje la cadena exacta documentada Stream idle timeout - no chunks received; en estas versiones el watchdog por bytes imprimió stream idle: no bytes for 10000ms. Tu mensaje puede variar según la versión y el tipo de conexión. Segunda: mi simulado no es la API real. Tercera: ejecuté todo en modo no interactivo -p, así que no vi el aviso interactivo «response above may be incomplete».

La solución: subir el tiempo límite

La recomendación de la documentación es subir CLAUDE_STREAM_IDLE_TIMEOUT_MS hasta cubrir tu pausa más larga. Ponlo en el perfil de tu shell:

export CLAUDE_STREAM_IDLE_TIMEOUT_MS=1800000

o en el bloque env de tu archivo de ajustes (mi prueba usó el mismo mecanismo con la variable de bytes):

{"env": {"CLAUDE_STREAM_IDLE_TIMEOUT_MS": "1800000"}}

Dónde está el archivo de ajustes se explica en ubicación de settings.json de Claude Code. Reglas de la documentación:

• CLAUDE_STREAM_IDLE_TIMEOUT_MS fija a la vez el límite por eventos y el de bytes. Claude Code sube cualquier valor menor de 300000 (5 minutos) a 300000, y limita el de bytes a 30 minutos. Confirmé la subida: 10000 actuó como 300 s en mi segunda prueba.
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS cambia solo el watchdog por bytes, de 10 segundos a 30 minutos, y requiere Claude Code 2.1.210 o posterior.
• API_TIMEOUT_MS limita cuánto espera Claude Code las cabeceras de respuesta, no cuánto puede callar un flujo después, así que aquí no es la solución.
• Un tiempo límite más largo también significa que una conexión realmente muerta tarda más en detectarse.

Cosas que no funcionan como parecen

• Bajar la variable no hace que falle antes. Por el mínimo de 300000, poner 60000 debería dejar 300 s en el watchdog por eventos (lo dice la documentación y mi prueba con 10000 se comportó así). Para fallar antes, usa la variable de bytes (mínimo 10 s).
• Apagar un watchdog no es una solución. La documentación dice que CLAUDE_ENABLE_STREAM_WATCHDOG=0 y CLAUDE_ENABLE_BYTE_WATCHDOG=0 apagan los temporizadores, y una conexión muerta ya no tiene salida temprana. No probé un bloqueo real más allá de los dos tiempos límite de arriba.
• El proxy tiene su propio tiempo límite. Si tu pasarela o proxy inverso cierra las conexiones inactivas antes que Claude Code, subir solo el valor de Claude Code no cambia nada. Sube también el del proxy.

Revisa el lado de la red

La sospechosa habitual de la documentación es una pasarela, proxy o VPN que retiene la conexión mientras el modelo piensa. Una incidencia de GitHub (anthropics/claude-code #70217) describe a un usuario cuyo NAT del ISP cortaba conexiones inactivas durante unos segundos; no verifiqué ese informe. Si el error aparece solo en una red, prueba desde otra antes de tocar los temporizadores.

Mensajes relacionados

Este error es distinto de «streaming response ended before any complete data», de 529 overloaded y de «unable to connect to API». Hay más en la lista de errores de Claude Code.

Preguntas frecuentes

¿Está caída la API de Anthropic cuando veo esto?

No necesariamente. El error viene del temporizador dentro de Claude Code. Te dice que el flujo estuvo en silencio más tiempo del que permite el temporizador, sea cual sea el motivo.

¿Qué hago justo después del error?

En una sesión interactiva la documentación dice que respondas continue; Claude Code conserva todos los bloques terminados y descarta el último interrumpido. No lo probé.

¿Un valor mayor ralentiza el uso normal?

No. El temporizador solo importa cuando un flujo se queda en silencio. Decide cuánto espera Claude Code antes de rendirse.

Fuentes y notas de prueba

• Documentación de Anthropic: configuración de red, «Streaming idle watchdogs» (code.claude.com/docs/en/network-config); referencia de errores (code.claude.com/docs/en/errors); variables de entorno (code.claude.com/docs/en/env-vars).
• Probado por mí: Claude Code 2.1.312 y 2.1.319 en Linux contra un servidor simulado que se queda en silencio, con CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS, CLAUDE_STREAM_IDLE_TIMEOUT_MS con el watchdog de bytes apagado y una entrada env en el archivo de ajustes.
• No probado: la API real de Anthropic, pasarelas, Bedrock, modo interactivo, la cadena de error documentada exacta, el comportamiento de continue.