Referencia de errores

Busca mensajes de error en tiempo de ejecución de Claude Code con lo que cada uno significa y cómo solucionarlo.

Esta página enumera los errores en tiempo de ejecución que Claude Code muestra y cómo recuperarte de cada uno, además de qué verificar cuando las respuestas parecen estar mal sin un error. Para errores de instalación como command not found o fallos de TLS durante la configuración, consulta Solucionar problemas de instalación e inicio de sesión.

Excepto por errores de Wrapper e IDE, que el programa de lanzamiento imprime en lugar de Claude Code mismo, estos errores y comandos de recuperación se aplican en toda la CLI, la aplicación de escritorio y sesiones en la nube, ya que las tres envuelven la misma CLI de Claude Code. Para otros problemas específicos de la superficie, consulta la sección de solución de problemas en la página de esa superficie.

Encuentra tu error

Busca el mensaje que ves en la tabla y ve a la sección correspondiente.

Reintentos automáticos

Claude Code reintenta fallos transitorios hasta 10 veces con retroceso exponencial antes de mostrarte un error. No siempre reintenta un fallo que llega a mitad de la respuesta de Claude. Cuando ves uno de los errores de esta página, Claude Code ya ha realizado los reintentos que corresponden a ese fallo.

Claude Code reintenta estos fallos:

• Errores del servidor, respuestas de sobrecarga y tiempos de espera de solicitud agotados que llegan antes de que cualquier parte de la respuesta de Claude se haya enviado en streaming.
• Un error del servidor o una respuesta de sobrecarga que llega después de que Claude ha terminado de pensar pero antes de que haya comenzado cualquier texto o llamada a herramienta. Claude Code reintenta un error del servidor en ese punto hasta dos veces. Antes de v2.1.284, Claude Code terminaba el turno con el error en ese punto.
• Conexiones perdidas. Cuando una conexión se cae a mitad de una solicitud antes de que Claude haya completado cualquier parte de su respuesta, incluido su pensamiento, Claude Code reenvía la solicitud con el mismo retroceso y el turno continúa, incluso si algo de texto ya había comenzado a enviarse en streaming. Cuando se cae después de que Claude ha terminado de pensar pero antes de que haya comenzado cualquier texto o llamada a herramienta, Claude Code en su lugar reenvía la solicitud hasta dos veces en rápida sucesión, y termina el turno con Connection lost before a response was produced si la conexión sigue cayéndose en ese punto.
• Una conexión que Claude Code detecta que se rompió porque tu computadora entró en suspensión a mitad de una solicitud. Claude Code la cuenta como una conexión perdida según las reglas anteriores; una vez que la etiqueta de reintento nombra la razón específica, dice Connection lost while your computer was asleep, y si el turno termina después de que Claude ha terminado de pensar pero antes de cualquier texto o llamada a herramienta, el mensaje dice Your computer went to sleep before a response was produced.
• Un stream de respuesta estancado, cuando los encabezados de respuesta han llegado pero ninguna parte de la respuesta de Claude ha llegado, o cuando Claude ha terminado de pensar pero no ha comenzado ningún texto ni llamada a herramienta: Claude Code aborta la conexión estancada y reenvía la solicitud como máximo una vez, fuera del presupuesto de 10 intentos anterior. Si la respuesta se estanca una segunda vez después de que Claude ha terminado de pensar pero antes de cualquier texto o llamada a herramienta, Claude Code termina el turno con The response stalled before a response was produced.
• Una solicitud en streaming a la que la API nunca responde con encabezados de respuesta, en una conexión donde se aplica el plazo del primer byte: Claude Code la aborta al cumplirse el plazo y la reenvía como máximo una vez por solicitud al modelo, dentro del presupuesto de reintentos, y luego termina el turno con No response from API si ese intento también queda sin respuesta. En otras conexiones, la solicitud espera hasta API_TIMEOUT_MS. Cuando estableces CLAUDE_CODE_RETRY_WATCHDOG, el límite de un reintento no se aplica.
• Limitaciones temporales 429, pero no el 429 de límite de gasto de un gateway, que no es una limitación; consulta Spend limit reached.
  • Cuando has iniciado sesión con una suscripción de claude.ai, esto incluye limitaciones 429 que no llevan los encabezados de cuota de tu plan. Antes de v2.1.199, Claude Code reintentaba esas limitaciones solo para inicios de sesión con clave de API y Enterprise.
• Una solicitud rechazada porque la entrada más max_tokens excede el límite de contexto. Reenviarla sin cambios fallaría de la misma manera, por lo que Claude Code reintenta con un max_tokens reducido, y deja de reintentar y compacta en su lugar en dos casos:
  • Cuando ninguna reducción puede caber, por ejemplo cuando la conversación misma casi llena la ventana de contexto.
  • Cuando un reintento no puede reducir max_tokens más. Antes de v2.1.218, Claude Code podía reenviar una solicitud reducida que aún no cabía, como cuando el presupuesto de pensamiento extendido excedía el contexto restante, hasta que se agotaba el presupuesto de reintentos.
• Una credencial de Google Cloud expirada o faltante en Google Cloud's Agent Platform, o credenciales de AWS que no se pueden cargar en tu máquina. Claude Code descarta sus credenciales en caché y reintenta hasta dos veces, luego reporta el error para que puedas volver a autenticarte de inmediato, como se describe en Could not load AWS or Google Cloud credentials. Antes de v2.1.228, Claude Code reintentaba una credencial de Google Cloud fallida durante todo el presupuesto de reintentos antes de mostrar el error.
• Un 401 o 403 de la API de Anthropic, directamente o a través de un gateway de LLM, mientras un script apiKeyHelper suministra la credencial. Claude Code vuelve a ejecutar el script y reintenta con su salida nueva, dentro de todo el presupuesto de reintentos. Cuando el script mismo falla en la nueva ejecución, Claude Code muestra Your apiKeyHelper script is failing en su lugar.

Antes de v2.1.227, Connection lost before a response was produced decía Connection closed while thinking, before producing a response y The response stalled before a response was produced decía Response stalled while thinking, before producing a response.

Claude Code no reintenta estos fallos:

• Un fallo de validación de certificado TLS, como un proxy que inspecciona TLS, un paquete NODE_EXTRA_CA_CERTS faltante o un certificado expirado. Claude Code reporta el error en el primer intento, para que puedas corregir la configuración del certificado de inmediato; consulta SSL certificate errors. Claude Code sigue reintentando condiciones TLS transitorias, como un tiempo de espera agotado en el handshake. Antes de v2.1.199, Claude Code reintentaba los fallos de certificado durante todo el presupuesto de reintentos antes de mostrar el error.
• Un error del servidor, una conexión perdida o un stream estancado que llega después de que Claude ha completado un bloque de texto o una llamada a herramienta, o ha comenzado uno después de terminar su pensamiento, pero antes de que termine la respuesta. Claude Code no vuelve a ejecutar la solicitud, porque eso podría ejecutar las mismas llamadas a herramientas dos veces. Conserva lo que Claude completó, ejecuta las llamadas a herramientas que Claude terminó y continúa el turno a partir de sus resultados. Para saber lo que ves en una sesión interactiva y en una no interactiva, lee The response above may be incomplete. Antes de v2.1.199, Claude Code descartaba la salida parcial y reportaba todo el turno como un error cuando un error del servidor llegaba a mitad del streaming.
• Un fallo que llega después de que Claude ha terminado la respuesta: no hay nada que reintentar, por lo que Claude Code conserva la respuesta completa y termina el turno normalmente.
• Una respuesta en streaming de Amazon Bedrock con un content-type inesperado, porque el gateway o proxy que reescribe la respuesta reescribiría el reintento de la misma manera. Requiere Claude Code v2.1.208 o posterior.
• Un reintento sin streaming de una solicitud en streaming fallida que obtiene un estado de éxito pero ningún mensaje de la API de Claude en el cuerpo. Claude Code termina el turno con ese error.
• Una solicitud que la verificación de políticas de tu organización rechazó, que aparece como una línea API Error: con el mensaje de denegación. Los administradores de tu organización configuran la verificación con Inference hooks, una función de Claude Enterprise, y el mensaje termina con las instrucciones que configuraron o, de forma predeterminada, te indica que te comuniques con ellos. Claude Code no reenvía la solicitud denegada al mismo modelo ni a un modelo de respaldo, porque la denegación se refiere al contenido de la solicitud y no al modelo. Antes de v2.1.239, Claude Code podía reenviar una solicitud denegada, sin streaming o en un modelo de respaldo configurado, antes de mostrarte la denegación.

Lo que ves mientras Claude Code reintenta o espera

Mientras reintenta, el spinner muestra una cuenta regresiva Retrying in Ns · attempt x/y después de una etiqueta de error. La etiqueta nombra la razón específica desde el primer intento para fallos sobre los que puedes actuar de inmediato: la red está caída, falló un handshake TLS o alcanzaste un rate limit. Para otros errores, al principio dice API error. A partir de v2.1.198, cambia a la razón específica desde el tercer intento, o en el intento final cuando CLAUDE_CODE_MAX_RETRIES permite menos de tres; las versiones anteriores cambian solo en el intento final.

A partir de v2.1.198, la sugerencia habitual del spinner se suprime durante los reintentos. Una vez que se revela la razón del error, si el fallo es una sobrecarga 529, la línea debajo de la cuenta regresiva también indica dónde verificar el estado del servicio: status.claude.com en la API de Anthropic, o el host del proveedor o gateway nombrado en el mensaje en otras configuraciones.

Si no llegan datos en el stream de respuesta durante 20 segundos mientras una solicitud sigue pendiente, el spinner muestra Waiting for API response · will retry in … · check your network antes de que haya comenzado ningún reintento. La solicitud aún no ha fallado: la cuenta regresiva corre hasta el punto en que Claude Code aborta la conexión estancada. Después de abortarla, lo que ves depende de cuánto había avanzado la respuesta:

• Antes de que Claude haya completado un bloque de texto o una llamada a herramienta, o haya comenzado uno después de terminar su pensamiento, Claude Code reintenta la solicitud o termina el turno con un error. Reintentos automáticos indica qué estancamientos reintenta y cuántas veces.
• Después de que Claude ha completado un bloque de texto o una llamada a herramienta, o ha comenzado uno después de terminar su pensamiento, pero antes de que Claude haya terminado la respuesta, Claude Code conserva lo que Claude completó, continúa el turno a partir de las llamadas a herramientas que Claude terminó y muestra The response above may be incomplete. En una sesión no interactiva, y para la respuesta de un subagente en cualquier sesión, Claude Code puede primero pedirle a Claude que continúe la respuesta; esa entrada indica cuándo lo hace y cuándo sigues viendo el aviso allí.
• Después de que Claude terminó la respuesta, Claude Code termina el turno normalmente.

El banner desaparece por sí solo una vez que los datos se reanudan o un reintento tiene éxito. Si reaparece en cada intento, trátalo como un problema de red. Antes de v2.1.185, el banner aparecía después de 10 segundos con una redacción diferente.

Mientras Claude consulta al asesor, el banner aparece después de 90 segundos sin datos en lugar de 20, porque una revisión larga del asesor puede no enviar nada durante bastante más de 20 segundos. Antes de v2.1.214, el umbral de 20 segundos también se aplicaba durante las llamadas al asesor, por lo que el banner aparecía durante las revisiones del asesor incluso cuando no pasaba nada malo.

Ajustar el comportamiento de reintentos

Puedes ajustar el comportamiento de reintentos con estas variables de entorno:

Errores del servidor

La mayoría de estos errores provienen del proveedor de inferencia: el servicio de Anthropic en la API de Anthropic, y el servicio detrás del endpoint de ese proveedor en Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry o un gateway personalizado. Auto mode cannot determine the safety of an action y Agent terminated early due to an API error también cubren causas de tu lado, como una cuenta de Amazon Bedrock que no puede invocar el modelo clasificador o un subagente que alcanzó un límite de uso.

API Error: 500 Internal server error

Claude Code muestra el código de estado y el mensaje de error de la API para cualquier respuesta 5xx. El ejemplo a continuación muestra una respuesta 500 en la API de Anthropic:

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

La oración final indica dónde verificar el estado del servicio y varía según el proveedor. Las configuraciones de Amazon Bedrock, Google Cloud's Agent Platform y Microsoft Foundry nombran el estado del servicio de ese proveedor. Un ANTHROPIC_BASE_URL personalizado nombra el host del gateway.

Un 5xx de la propia API indica un fallo inesperado dentro de la API. No lo causa tu prompt, tu configuración ni tu cuenta.

Cuando un proxy, balanceador de carga o gateway responde con una página de error HTML, el mensaje muestra el código de estado y el título de la página, como API Error: 502 Bad Gateway. Para una página sin título, el mensaje muestra en su lugar el código de estado y su nombre estándar. Antes de v2.1.281, el código de estado se omitía cuando la página tenía un título, y el marcado sin procesar de la página se imprimía cuando no tenía ninguno.

Qué hacer:

• Consulta status.claude.com, o la página de estado del proveedor nombrada en el mensaje, para ver si hay incidentes activos
• Espera un minuto y luego envía tu mensaje de nuevo. Tu mensaje original sigue en la conversación, así que para un prompt largo puedes escribir try again en lugar de pegarlo completo.
• Si el error persiste sin ningún incidente publicado, ejecuta /feedback para que Anthropic pueda investigar con los detalles de tu solicitud. Consulta Informar un error si /feedback no está disponible en tu entorno.

API Error: Repeated 529 Overloaded errors

La API está temporalmente al límite de su capacidad para todos los usuarios. Claude Code ya reintentó varias veces antes de mostrar este mensaje:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

La oración final varía según el proveedor de la misma manera que en el error 500 anterior.

Un 529 no es tu límite de uso y no cuenta contra tu cuota.

Qué hacer:

• Consulta status.claude.com, o la página de estado del proveedor nombrada en el mensaje, para ver si hay avisos de capacidad

• Vuelve a intentarlo en unos minutos

• Ejecuta /model y cambia a un modelo diferente para seguir trabajando, ya que la capacidad se controla por modelo. Claude Code te pide que hagas esto cuando un modelo está bajo una carga particularmente alta, por ejemplo Opus is experiencing high load, please use /model to switch to Sonnet. En los modelos Fable, el mensaje nombra Fable.

  En una sesión que ejecuta la aplicación Claude Desktop, como la pestaña Code o Cowork, el mensaje dice Opus is experiencing high load. Switch to Sonnet. y cambias de modelo con el selector de modelos de la aplicación.

Request timed out

La API no respondió antes del plazo de conexión.

Request timed out

Esto puede ocurrir durante períodos de alta carga o cuando el modelo está generando una respuesta muy grande. El tiempo de espera predeterminado de la solicitud es de 10 minutos.

Qué hacer:

• Reintenta la solicitud
• Si la causa es una red lenta o un proxy, aumenta API_TIMEOUT_MS como se describe en Reintentos automáticos
• Si se agota el tiempo de espera con frecuencia y tu red por lo demás funciona bien, consulta Errores de red y de conexión más abajo

No response from API

Claude Code envió una solicitud en streaming y la API no devolvió encabezados de respuesta dentro del plazo para el primer byte, así que Claude Code abortó la solicitud en lugar de esperar el tiempo de espera completo de la solicitud, API_TIMEOUT_MS, de 10 minutos por defecto. Claude Code envía la solicitud de nuevo como máximo una vez, si el presupuesto de reintentos lo permite. Cuando el reintento tampoco recibe respuesta, el turno termina con este mensaje, que muestra cuánto tiempo esperó cada intento. Cuando estableces CLAUDE_CODE_RETRY_WATCHDOG, el límite de un solo reintento no se aplica y Claude Code reintenta según el presupuesto descrito en Ajustar el comportamiento de los reintentos.

API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

Claude Code establece por separado la espera de los encabezados de respuesta del primer intento y la del reintento:

• Primer intento: CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS cuando lo estableces en 1 o más, limitado a un valor entre 10 segundos y 30 minutos. De lo contrario, Claude Code usa el tiempo de espera del watchdog a nivel de bytes indicado en Watchdogs de inactividad del streaming, así que las variables que cambian ese tiempo de espera también cambian esta espera. En cualquier caso, Claude Code agrega un segundo por cada 32KB del cuerpo de la solicitud.
• Reintento: un segundo menos que API_TIMEOUT_MS, poco menos de 10 minutos por defecto, para que el reintento pueda durar más que un proxy o gateway que retiene la respuesta hasta que termina la generación. En Amazon Bedrock, el reintento usa el mismo plazo que el primer intento, y el mensaje muestra una duración en lugar de dos.

Ninguna de las dos esperas supera un segundo menos que un API_TIMEOUT_MS positivo, y un API_TIMEOUT_MS positivo inferior a 11 segundos desactiva el plazo. El watchdog a nivel de bytes se inicia solo cuando llegan los encabezados de respuesta, así que una respuesta que deja de enviar bytes después de eso sigue las reglas de streaming detenido en lugar de este plazo.

Qué hacer:

• Envía tu mensaje de nuevo. Tu mensaje original sigue en la conversación, así que para un prompt largo puedes escribir try again en lugar de pegarlo completo.
• Si se repite, trátalo como un problema de red o de proxy.
• Si un proxy o gateway de tu red retiene las respuestas hasta que se completan, aumenta API_TIMEOUT_MS para que el reintento espere más. En Amazon Bedrock, aumenta también CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.
• Si al primer intento se le sigue agotando el tiempo de espera y luego el reintento tiene éxito, aumenta CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS para que el primer intento también espere lo suficiente.

Antes de v2.1.242, Claude Code esperaba el tiempo de espera completo de la solicitud, API_TIMEOUT_MS, de 10 minutos por defecto, antes de dar por fallida una solicitud en streaming sin respuesta. Antes de v2.1.261, el reintento esperaba el mismo plazo que el primer intento y el mensaje no mostraba duraciones.

The response above may be incomplete

Una solicitud en streaming falló mientras la respuesta aún estaba en curso, después de que Claude completó un bloque de texto o una llamada a herramienta, o de que empezó uno tras terminar su pensamiento. Reenviar la solicitud podría ejecutar las mismas llamadas a herramientas dos veces, así que Claude Code conserva la salida que Claude completó y agrega este aviso en lugar de descartar el turno. La variante que ves indica la causa:

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection lost mid-response. The response above may be incomplete.
API Error: Your computer went to sleep mid-response. The response above may be incomplete.
API Error: The response stopped arriving. The response above may be incomplete.
API Error: Part of the response never arrived. The response above may be incomplete.
API Error: The response stream was malformed. The response above may be incomplete.

• Server error mid-response: un error de sobrecarga o un error de servidor 5xx a mitad del streaming. Esta variante requiere Claude Code v2.1.199 o posterior; antes, en ese caso se descartaba la salida parcial y se informaba todo el turno como un error.
• Connection lost mid-response: la conexión se perdió. También ves esta variante cuando un proxy o gateway cierra limpiamente el cuerpo de la respuesta antes de que la respuesta haya terminado.
• Your computer went to sleep mid-response: Claude Code detectó que tu computadora entró en suspensión mientras la respuesta se transmitía en streaming. Cuando tu computadora se reactiva, Claude Code trata la conexión como rota y deja de leer de ella.
• Part of the response never arrived: un evento del streaming se perdió entre la API y Claude Code, así que un evento posterior hizo referencia a contenido que nunca llegó. Antes de v2.1.281, en este caso el turno terminaba con API Error: Content block not found.
• The response stream was malformed: llegó un evento para un bloque de contenido que ya había terminado, o llegó un evento dañado. Un evento dañado es aquel cuyos datos no son JSON válido, cuyo contenido falta o cuyo contenido no coincide con el tipo del evento. Antes de v2.1.284, en su lugar aparecía el error sin procesar del analizador, como uno que empieza con API Error: JSON Parse error, cuando un evento con JSON no válido llegaba después de que Claude había completado su pensamiento, un bloque de texto o una llamada a herramienta.
• The response stopped arriving: la conexión siguió abierta pero dejó de entregar datos, así que el watchdog de inactividad del streaming la abortó. Antes de v2.1.222, Claude Code también podía informar este fallo en conexiones a un gateway a través de ANTHROPIC_BASE_URL o ANTHROPIC_AWS_BASE_URL mientras aún llegaban los pings de keep-alive del servidor, porque allí solo contaba los eventos de respuesta analizados; actualizar elimina esos tiempos de espera agotados falsos en esas rutas. Los gateways a los que se accede mediante una URL base de proveedor como ANTHROPIC_BEDROCK_BASE_URL no están cubiertos por el watchdog de bytes; consulta Watchdogs de inactividad del streaming.

Antes de v2.1.227, Connection lost mid-response decía Connection closed mid-response y The response stopped arriving decía Response stalled mid-stream.

Cuando un evento del streaming perdido, duplicado o dañado llega antes de que Claude haya empezado cualquier texto o llamada a herramienta, no ves este aviso:

• Si Claude solo había completado su pensamiento, Claude Code vuelve a emitir la solicitud. Cuando los streamings reemitidos fallan de la misma manera, el turno termina con Part of the response never arrived and no response was produced. Try again. o The response stream was malformed and no response was produced. Try again.
• Si no se había completado nada, Claude Code reenvía en su lugar la solicitud sin streaming. Si desactivaste ese respaldo con CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, el turno termina con API Error: Content block not found para un evento perdido o API Error: Content block already closed para uno duplicado. Para un evento dañado con el respaldo desactivado, el turno termina con API Error: Stream event unreadable o con el error sin procesar del analizador.

En cuatro casos, Claude Code maneja el fallo sin mostrar este aviso de inmediato:

• Si ocurre antes en la respuesta, Claude Code reintenta el fallo o termina el turno con un error diferente. Consulta Reintentos automáticos.
• Cuando uno de estos fallos llega después de que Claude terminó la respuesta, Claude Code conserva la respuesta completa y termina el turno normalmente, sin este aviso. Antes de v2.1.222, Claude Code mostraba este aviso cuando la conexión se perdía o se detenía después de que la respuesta terminaba, e informaba el turno como un error aunque la respuesta estuviera completa.
• En una sesión no interactiva, como una ejecución con -p, una ejecución del Agent SDK o una sesión en la nube, no tienes que enviar continue tú mismo cuando la respuesta cortada está en la conversación principal y contiene texto pero ninguna llamada a herramienta: Claude Code conserva la salida parcial y le pide a Claude que continúe desde donde se detuvo, hasta tres veces seguidas. Solo ves este aviso para una respuesta así cuando Claude Code agotó esas continuaciones. Antes de v2.1.246, Claude Code terminaba un turno no interactivo con este aviso en el primer corte.
• En un subagente, sea la sesión interactiva o no: cuando su respuesta cortada contiene texto pero ninguna llamada a herramienta, Claude Code le pide al subagente que continúe. El aviso se convierte en el último mensaje del subagente solo cuando esas continuaciones se agotan. Antes de v2.1.257, un subagente mostraba este aviso en el primer corte.

Qué hacer:

• En una sesión interactiva, lee la respuesta que queda en pantalla: Claude Code conserva cada bloque que Claude completó antes del error, pero descarta un bloque final interrumpido cuando termina el turno, así que es posible que falten las últimas oraciones o llamadas a herramientas. Responde con continue para que Claude retome desde su último bloque completado.
• En modo no interactivo (-p):
  • Con la salida de texto predeterminada, Claude Code imprime el último bloque de texto completado que aún conserva de antes en el turno, seguido de este mensaje. Cuando no conserva ninguno, Claude Code imprime solo este mensaje, por ejemplo porque Claude Code compactó la conversación a mitad del turno y borró ese texto. Antes de v2.1.219, Claude Code imprimía solo este mensaje en la salida de texto de -p y descartaba la respuesta que ya había producido.
  • Con --output-format json o stream-json, Claude Code informa este mensaje en el campo result.
  • Para continuar el turno cuando la conexión sea estable, reanuda la sesión y envía continue como se describe en Continuar conversaciones.

Auto mode cannot determine the safety of an action

El modelo que usa el modo automático para clasificar acciones no pudo producir una decisión, así que el modo automático no aprobó la acción automáticamente. El mensaje que ves depende de cómo falló el clasificador.

Las lecturas, búsquedas y ediciones dentro de tu directorio de trabajo omiten el clasificador, así que siguen funcionando en todos estos casos.

Cuando el modelo clasificador no está disponible:

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

Cuando Claude Code puede determinar la categoría del fallo, la nombra entre paréntesis después de temporarily unavailable, por ejemplo <model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now. Las categorías son (rate-limited), (overloaded), (server error), (timed out) y (connection failed). Si (timed out) o (connection failed) se repite, revisa tu conexión; consulta Unable to connect to API. Antes de v2.1.229, el mensaje nunca nombraba una categoría y decía Wait briefly and then try this action again.

Cuando ninguna categoría encaja, el mensaje aparece sin categoría entre paréntesis; más de un fallo produce esa forma. En Amazon Bedrock, incluido el endpoint de Mantle, también aparece cuando tu cuenta de AWS no puede invocar el modelo nombrado en el mensaje, y ese fallo se repite en cada reintento hasta que tu cuenta obtenga acceso al modelo.

Qué hacer:

• Reintenta después de unos segundos; Claude ve el mismo mensaje y normalmente reintenta por su cuenta. Un fallo transitorio no tiene relación con los requisitos del modo automático; no necesitas cambiar la configuración
• Si los reintentos siguen fallando, continúa con tareas de solo lectura y vuelve más tarde a la acción bloqueada
• En Amazon Bedrock, si el mensaje reaparece en cada reintento, comprueba que tu cuenta pueda invocar el modelo que nombra: para los modelos estándar de Amazon Bedrock, confirma que tu política de IAM permite invocarlo; para los IDs de modelo de Mantle, contacta al equipo de tu cuenta de AWS

Cuando una solicitud al clasificador falla porque tu token de OAuth expiró o fue rotado por otra sesión, Claude Code actualiza el token y reintenta la solicitud una vez, así que una expiración habitual del token no aparece como este mensaje. Antes de v2.1.216, un token expirado o rotado hacía fallar cada solicitud al clasificador, y el modo automático denegaba cada acción verificada con este mensaje hasta que se actualizaba el token.

Cuando el clasificador devolvió una respuesta que no se pudo analizar:

Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

Qué hacer:

• Reintenta la acción; normalmente funciona en el siguiente intento
• Ejecuta claude --debug y repite la acción para ver los detalles en el registro de depuración

Cuando una verificación de seguridad de la API independiente bloqueó la solicitud al clasificador debido a contenido anterior de la conversación:

Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

Claude Code deniega la acción, pero le indica a Claude que esto no es un juicio de que la acción sea insegura y que continúe con otras tareas en lugar de reintentar. Estas denegaciones no cuentan para los umbrales de pausa del modo automático. En una ejecución no interactiva con -p, Claude Code no detiene la ejecución. Lo que recibe Claude depende de dónde solicitó la acción:

• A un subagente en segundo plano en una ejecución con -p sin --input-format stream-json, Claude Code le devuelve un resultado de error que contiene Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode
• En todos los demás casos, incluidas las sesiones interactivas y la conversación principal de una ejecución con -p, Claude Code le devuelve esa denegación a Claude

Antes de v2.1.225, Claude Code contaba estos rechazos para los umbrales de pausa y devolvía el mismo mensaje de rechazo que un bloqueo real del clasificador.

Qué hacer:

• Esto no es una decisión sobre tu acción. Contenido que ya estaba en tu conversación activó un filtro de seguridad en la API cuando el modo automático envió la conversación al clasificador
• Reintentar no servirá; el mismo contenido de la conversación volverá a activar el filtro
• En una sesión interactiva, cambia a otro modo de permisos para poder aprobar la acción cuando se te solicite
• Inicia una conversación nueva sin el contenido que activa el filtro

Cuando la conversación superó el tamaño de la ventana de contexto del clasificador:

Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

Lo que sucede con la acción depende de dónde la solicitó Claude:

• En una sesión interactiva, el modo automático recurre a una solicitud de permiso normal para esa acción, para que puedas aprobarla o denegarla manualmente
• A un subagente en segundo plano en una ejecución no interactiva con -p sin --input-format stream-json, Claude Code le devuelve un resultado de error que contiene Agent aborted: auto mode classifier transcript exceeded context window in headless mode, y la ejecución continúa
• En cualquier otro punto de una ejecución con -p sin --permission-prompt-tool, no hay ninguna solicitud a la que recurrir, así que la acción no se ejecuta y la ejecución continúa

Qué hacer:

• En una sesión interactiva, aprueba o deniega la acción en la solicitud que aparece
• En una sesión interactiva, ejecuta /compact para reducir el tamaño de la conversación y que las acciones siguientes vuelvan a caber en la ventana del clasificador

The server returned no safety verdict

Con la revisión del clasificador en el servidor, el modo automático deniega una acción cuando el servidor no da ningún veredicto sobre ella. La denegación nombra una categoría entre paréntesis cuando Claude Code puede determinarla, como (timed out):

The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.

El resto del mensaje le indica a Claude si un reintento puede ayudar. Antes de algunas de estas denegaciones, Claude Code espera para que el siguiente intento de Claude no llegue de inmediato. Durante la espera en una sesión interactiva, el spinner muestra Auto mode check unavailable con una cuenta regresiva, y al presionar Esc se interrumpe el turno.

Después de diez respuestas seguidas sin veredicto, el modo automático detiene el turno:

Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

El mensaje de detención aparece en un lugar distinto en cada tipo de sesión:

• En una sesión interactiva, el mensaje aparece como advertencia en la transcripción y el turno termina
• En una ejecución no interactiva con -p, la ejecución termina e informa un error de ejecución. Con la salida de texto predeterminada, el mensaje se imprime en stderr.
• Cuando un subagente alcanzó el límite, el subagente se detiene antes de terminar, y Claude recibe lo que haya producido junto con una nota de que el modo automático lo detuvo

Qué hacer:

• Envía otro mensaje para que Claude lo intente de nuevo. El recuento de respuestas se reinicia.
• Si la detención se repite y tus solicitudes pasan por un gateway de LLM o proxy, comprueba si corta las respuestas en streaming o las reescribe. Revisión del clasificador en el servidor indica qué comportamiento del gateway causa denegaciones, y la guía de compatibilidad de gateways enumera lo que debe pasar sin cambios.
• Establece CLAUDE_CODE_AUTO_MODE_SERVER=0 antes de iniciar Claude Code para que use en su lugar sus propias solicitudes al clasificador. Antes de v2.1.281, Claude Code no leía la variable en una conexión directa a la API de Anthropic.
• Para aprobar tú mismo las acciones, sal del modo automático

Antes de v2.1.280, Claude Code denegaba de inmediato cada acción de una respuesta sin veredicto y nunca detenía el turno.

Agent terminated early due to an API error

La solicitud a la API de un subagente falló de forma definitiva, por ejemplo porque se alcanzó un límite de uso o se agotaron los reintentos de un error de servidor, así que el subagente se detuvo antes de terminar su tarea. Este mensaje requiere Claude Code v2.1.199 o posterior; antes, el texto del error de la API se devolvía a Claude como si fuera el resultado del subagente.

Agent terminated early due to an API error: <error detail>

Qué hacer:

• Busca el detalle del error que aparece después de los dos puntos en su propia sección de esta página, como Límites de uso o Errores del servidor, y sigue los pasos de esa sección
• Cuando se resuelva el error subyacente, pídele a Claude que reintente la tarea o reanuda el subagente

Cuando un rate limit, una sobrecarga o un error de servidor interrumpe un subagente en primer plano que ya produjo salida de texto, Claude recibe esa salida parcial marcada como incompleta en lugar de este error. Un subagente cuya única salida fueron llamadas a herramientas también recibe este error; en v2.1.199, ese caso devolvía en su lugar un resultado parcial vacío. Consulta Errores de API en subagentes.

Límites de uso

La mayoría de los errores en esta sección significan que se ha alcanzado una cuota vinculada a su cuenta o plan. Tres funcionan de manera diferente: Server is temporarily limiting requests es un acelerador del lado del servidor no relacionado con su cuota de plan, Usage credits required for 1M context es una verificación de derechos en lugar de una cuota agotada, y The prompt to confirm went unanswered significa que un aviso de consentimiento de créditos de uso se cerró sin respuesta, independientemente de si se alcanzó una cuota.

You've hit your session limit

Los planes de suscripción incluyen una asignación de uso móvil. Cuando se agota, verá uno de estos mensajes:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

Claude Code bloquea las solicitudes adicionales hasta la hora de reinicio que se muestra en el mensaje. Los límites de sesión y semanales se comparten entre todos los modelos, por lo que cambiar de modelo no restaura el acceso. Los límites de Opus y Sonnet se aplican solo a las solicitudes a esa familia de modelos, por lo que cambiar a un modelo fuera de la familia con /model le permite seguir trabajando.

En una sesión interactiva iniciada con una suscripción de claude.ai, Claude Code también puede esperar en la sesión abierta y continuar la tarea interrumpida poco después del reinicio. Consulta Wait for a usage limit to reset para ver qué se muestra, cómo iniciar o cancelar una espera y cómo desactivar la continuación automática. Antes de v2.1.234, Claude Code no ofrecía esta espera.

El uso se cuenta contra las asignaciones de sesión y semanales al mismo tiempo. Una única ráfaga de actividad pesada, como un gran fanout de flujo de trabajo, puede agotar la asignación semanal antes de que se reinicie la ventana de sesión.

Qué hacer:

• Espere la hora de reinicio que se muestra en el error
• En la pestaña Code de la aplicación de escritorio, la tarjeta de límite de sesión ofrece una casilla de verificación Auto-continue when limits reset. La tarjeta de límite semanal no. Cuando está marcada, la aplicación de escritorio reintenta el turno interrumpido después del reinicio y muestra la hora del reintento en la tarjeta. La casilla de verificación de escritorio y la configuración Continue automatically at usage limit de la CLI en /config son independientes, así que desactive cada una por separado.
• Para el límite de Opus o Sonnet, ejecute /model y cambie a un modelo fuera de esa familia para seguir trabajando. Cada modelo tiene su propio caché de aviso, por lo que la siguiente solicitud relee toda la conversación sin aciertos de caché; consulte Switching models
• Ejecute /usage para ver los límites de su plan y cuándo se reinician
• Ejecute /usage-credits para comprar uso adicional en Pro y Max, o para solicitarlo a su administrador en Team y Enterprise. Consulte usage credits for paid plans para ver cómo se factura esto.
• Para actualizar su plan para obtener límites base más altos, consulte claude.com/pricing

Antes de que se agote una ventana, Claude Code puede advertirle que ha utilizado la mayor parte de ella, con un mensaje como You've used 85% of your session limit · resets 3:45pm. Para ver su asignación restante continuamente, agregue los campos rate_limits a una línea de estado personalizada, o en la aplicación de escritorio haga clic en el anillo de uso junto al selector de modelo.

Usage credits required for 1M context

El modelo seleccionado utiliza la ventana de contexto extendida de 1M tokens, y su plan solo la incluye a través de créditos de uso.

API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

En una sesión que ejecuta la aplicación Claude Desktop, el aviso no nombra comandos: apunta a la página de configuración de uso de claude.ai, o en planes Team y Enterprise dice que active los créditos de uso en claude.ai/admin-settings/usage o que pida a su administrador.

Esta es una verificación de derechos, no un agotamiento de cuota. Se activa incluso cuando sus asignaciones de sesión y semanales tienen capacidad restante. Consulte Extended context para ver qué planes incluyen contexto de 1M directamente y cuáles requieren créditos de uso.

Cuando este error aparece a mitad de la conversación porque el contexto creció más allá de 200K tokens, Claude Code compacta automáticamente la conversación nuevamente bajo el límite de contexto estándar y mantiene la sesión en ese límite después, por lo que no se requiere acción. En versiones anteriores a v2.1.172, el error se repetía en cada solicitud posterior, incluida /compact; ejecute /clear en esas versiones para recuperarse. Los pasos a continuación se aplican cuando seleccionó explícitamente un modelo [1m].

Qué hacer:

• Ejecute /model y seleccione la variante sin el sufijo [1m] para volver a la ventana de contexto estándar
• Donde el mensaje menciona /usage-credits, ejecútelo para activar la facturación medida para la variante de 1M en Pro y Max, o para solicitar créditos de uso a su administrador en Team y Enterprise. Una vez que los créditos de uso estén activados, reinicie Claude Code o inicie una nueva sesión, lo que diga el mensaje. Hasta entonces, la sesión permanece en el límite de contexto estándar.
• Si el error persiste después de /model, un ID de modelo de 1M puede estar configurado en otro lugar. Consulte Setting your model para ver las ubicaciones de configuración a verificar en orden de prioridad.
• Para eliminar variantes de 1M del selector de modelo por completo, establezca CLAUDE_CODE_DISABLE_1M_CONTEXT=1

Antes de v2.1.268, el mensaje terminaba con run /usage-credits to turn them on, or /model to switch to standard context y no mencionaba reiniciar.

The prompt to confirm went unanswered

Si su cuenta requiere el consentimiento de créditos de uso de Fable, Claude Code le pide que confirme antes de que una solicitud de Fable facture créditos de uso. Cuando el aviso de consentimiento se cierra sin que nadie lo responda, Claude Code termina el turno con uno de estos mensajes:

Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change
Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

Los mensajes nombran el modelo Fable de la sesión, por lo que en Fable 5 leen continuing on Fable 5 y Fable 5 now uses usage credits. Antes de v2.1.257, el primer mensaje comenzaba Fable 5 limit reached.

Esto sucede en sesiones de Remote Control, sesiones en segundo plano, equipo de agentes sesiones de compañeros, y sesiones que otra aplicación aloja a través del Agent SDK. Para saber cuándo Claude Code cierra el aviso, consulte Fable and usage credits.

Qué hacer:

• Donde se ejecuta la sesión, en la terminal o en la aplicación que la aloja, envíe otro aviso y responda el aviso de consentimiento cuando reaparezca. Para una sesión en segundo plano, adjúntese a ella desde la vista de agentes primero. Reenviar desde un cliente de Remote Control muestra este mensaje nuevamente, porque el cliente no puede mostrar el aviso.
• Ejecute /model para cambiar a un modelo que no facture créditos de uso
• Para darse más tiempo, establezca dialogExpiry en un valor más largo o "never"

Antes de v2.1.236, este mensaje no aparecía: mientras un cliente de Remote Control estaba conectado, Claude Code esperaba 60 segundos una respuesta y luego continuaba el turno en su modelo predeterminado.

Server is temporarily limiting requests

La API aplicó un acelerador de corta duración que no está relacionado con su cuota de plan.

API Error: Server is temporarily limiting requests (not your usage limit)

Claude Code distingue estos de su límite de plan por la ausencia de los encabezados de cuota unificada que lleva una respuesta de límite real. A partir de v2.1.199, esto se reintenta automáticamente con retroceso antes de mostrarse, independientemente de cómo se autentique. En versiones anteriores, una sesión con una suscripción de claude.ai falló el turno en la primera ocurrencia; solo las claves API y los inicios de sesión de Enterprise lo reintentaron.

Qué hacer:

• Espere brevemente e intente de nuevo
• Consulte status.claude.com si persiste

Request rejected (429)

Ha alcanzado el límite de velocidad configurado para su clave API, proyecto de Amazon Bedrock o proyecto de Google Cloud.

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

La oración final nombra dónde verificar el estado del servicio y varía según el proveedor. Las configuraciones de Amazon Bedrock, Google Cloud's Agent Platform y Microsoft Foundry nombran el estado del servicio de ese proveedor en lugar de la página de estado de Anthropic. Un ANTHROPIC_BASE_URL personalizado nombra el host de la puerta de enlace.

Cuando un proxy, equilibrador de carga o puerta de enlace entre Claude Code y la API responde con su propia página HTML 429, el texto después del · es el título de esa página cuando tiene uno, como Too Many Requests. Antes de v2.1.281, el marcado completo de la página se imprimía después del ·.

Qué hacer:

• Ejecute /status y confirme que la credencial activa es la que espera. Un ANTHROPIC_API_KEY extraviado en su entorno puede enrutar solicitudes a través de una clave de nivel bajo en lugar de su suscripción.
• Consulte la consola de su proveedor para ver los límites activos y solicite un nivel más alto si es necesario
• Para claves API de Anthropic, consulte la referencia de límites de velocidad para ver cómo funcionan los niveles y cómo establecer límites por espacio de trabajo
• Reduzca la concurrencia: baje CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, evite ejecutar muchos subagentes paralelos, o cambie a un modelo más pequeño con /model para ejecuciones de alto volumen con scripts

You've hit your monthly spend limit

El uso incluido en su plan no puede cubrir esta solicitud, y los créditos de uso que de otro modo pagarían por ella han alcanzado un límite de gasto. Eso sucede cuando una de las ventanas de uso de su plan se ha agotado, o cuando la solicitud es una que solo los créditos de uso pagan, como una solicitud a un modelo que factura a créditos de uso. El mensaje nombra cuyo límite lo bloqueó. El texto después del · dice cómo aumentar ese límite, y varía con su plan y si usted gestiona la facturación:

You've hit your monthly spend limit · raise it at claude.ai/settings/usage
You've hit your individual spend limit · ask your admin for a higher limit
You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it
You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage
You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

team's shared budget es un presupuesto agrupado que un administrador asignó a un grupo al que pertenece; el mensaje no nombra el grupo. channel's monthly spend limit es el presupuesto del único canal de Slack en el que se ejecuta la sesión, por lo que su organización aún puede tener presupuesto fuera de él.

Cuando una de las ventanas de su plan es lo que se agotó, el mensaje también dice cuándo se reinicia esa ventana, por ejemplo · your session limit resets 3:45pm, y el acceso regresa entonces sin que nadie aumente el límite. En organizaciones con facturación basada en el uso, el mensaje dice usage limit en lugar de spend limit, como en You've hit your individual usage limit.

Antes de v2.1.239, el mensaje no nombraba la hora de reinicio de la ventana del plan. Antes de v2.1.268, el presupuesto agrupado de un grupo producía el mensaje individual spend limit en lugar de team's shared budget.

Si se conecta a través de una puerta de enlace de aplicaciones Claude y ve spend limit reached en minúsculas, ese es el límite de su operador de puerta de enlace en su lugar; consulte Spend limit reached.

Qué hacer:

• En Pro y Max, aumente su límite de gasto mensual en Settings > Usage en claude.ai, o ejecute /usage-credits
• En Team y Enterprise, aumente el límite en Admin settings > Usage si gestiona la facturación, o pida a un administrador que lo haga. /usage-credits envía esa solicitud a su administrador por usted
• Para el límite de un canal, pida a un propietario de la organización o al gerente del canal que lo aumente en claude.ai. Consulte Per-channel limits en la documentación de Claude Tag
• Si el mensaje nombra una hora de reinicio para la ventana de su plan, puede esperar en su lugar
• Ejecute /usage para ver las ventanas de su plan y cuándo se reinicia cada una

Spend limit reached

Se conecta a través de una puerta de enlace de aplicaciones Claude y ha superado un límite de gasto que estableció el operador de su puerta de enlace. La puerta de enlace bloquea sus solicitudes hasta que se reinicia el período nombrado o el operador aumenta el límite. Marca cada respuesta 429 bloqueada con x-should-retry: false, por lo que Claude Code muestra este mensaje sin reintentar.

spend limit reached (daily; resets 2026-08-09 00:00 UTC)

El mensaje nombra el período del límite y la hora de reinicio, y cuando el operador configuró un blocked_message, sus instrucciones lo siguen. Antes de v2.1.225, el mensaje leía solo spend limit reached; una puerta de enlace en una versión anterior aún envía esa forma más corta.

Qué hacer:

• Espere la hora de reinicio que nombra el mensaje, o siga las instrucciones del operador si el mensaje las lleva
• Pida al operador de su puerta de enlace que aumente el límite si lo alcanza rutinariamente

Un mensaje relacionado, spend limit unavailable, significa que la puerta de enlace no pudo leer sus registros de gasto y bloqueó la solicitud como precaución en lugar de sobre su límite. Generalmente se resuelve por sí solo; si persiste, informe al operador de su puerta de enlace.

Credit balance is too low

Su organización de Console se ha quedado sin créditos prepagados, o Claude Code está enviando sus solicitudes con una clave API de Console cuando pretendía usar su suscripción.

Credit balance is too low

Qué hacer:

• Si tiene un plan Pro, Max, Team o Enterprise y ve esto, ejecute /status y verifique la fila API key. Un ANTHROPIC_API_KEY aprobado en su entorno enruta solicitudes a través de esa clave en lugar de su suscripción. Desactívelo en el shell actual y elimínelo de su perfil de shell, luego reinicie claude. Ejecute /login si aún no ha iniciado sesión con su suscripción.
• Agregue créditos en platform.claude.com/settings/billing, y considere habilitar la recarga automática allí para que el saldo se rellene antes de que llegue a cero
• Establezca límites de gasto por espacio de trabajo en la Console para evitar que un único proyecto agote el saldo de la organización. Consulte Manage costs effectively.

Could not update your spend limit

El servidor rechazó un cambio de límite de gasto que realizó desde el aviso que aparece cuando alcanza su límite de gasto.

Could not update your spend limit: <reason from the server>

Cuando el servidor explica el rechazo, el mensaje termina con esa razón, y reintentar el mismo valor falla nuevamente. Cuando el fallo no tiene una razón proporcionada por el servidor, como una conexión perdida, el mensaje lee Could not update your spend limit. Press Enter to retry. y reintentar puede tener éxito. Antes de v2.1.216, Claude Code mostraba la forma genérica para cada fallo.

Qué hacer:

• Si el mensaje incluye una razón, elija un límite que la satisfaga, como una cantidad más baja
• Si el mensaje muestra solo la forma genérica, reintente; el fallo puede ser transitorio
• Si el cambio sigue fallando, hágalo desde su configuración de facturación de claude.ai en el navegador en su lugar

Errores de autenticación

Estos errores significan que Claude Code no puede demostrar ante la API quién eres. Ejecuta /status en cualquier momento para ver qué credencial está activa actualmente.

No has iniciado sesión

No hay ninguna credencial válida disponible para esta sesión.

Not logged in · Please run /login

En una sesión que ejecuta la aplicación Claude Desktop, como la pestaña Code o Cowork, el mensaje dice Authentication required · Sign in again to continue, y vuelves a iniciar sesión desde la aplicación.

Si inicias sesión con tu cuenta de claude.ai en otra ventana de Claude Code que usa el mismo directorio de configuración, una sesión interactiva que muestra este mensaje empieza a usar ese inicio de sesión por sí sola. No necesitas reiniciarla.

Antes de la v2.1.286 en macOS, la sesión podía seguir mostrando el mensaje después de que iniciaras sesión desde otra ventana. En esas versiones, reinicia la sesión que muestra el mensaje.

Qué hacer:

• Ejecuta /login para autenticarte con tu suscripción de Claude o tu cuenta de Console
• Si esperabas que una variable de entorno te autenticara, confirma que ANTHROPIC_API_KEY está definida y exportada en el shell desde el que iniciaste claude
• Para CI o automatización donde el inicio de sesión interactivo no es posible, configura un script apiKeyHelper que obtenga una clave al inicio
• Consulta Precedencia de autenticación para entender qué credencial usa Claude Code cuando hay varias presentes

Si se te pide iniciar sesión repetidamente, consulta No has iniciado sesión o el token expiró para ver las comprobaciones del reloj del sistema y los pasos de recuperación del almacenamiento de credenciales en macOS.

No se pudo resolver el método de autenticación

La sesión llegó al cliente de la API sin ninguna credencial. Las sesiones en segundo plano y las sesiones en la nube muestran este mensaje cuando el worker se inicia sin una credencial. Las ejecuciones interactivas, con -p y del Agent SDK informan la misma condición como No has iniciado sesión y escriben esta cadena solo en su registro de depuración, así que si la encontraste ahí, sigue esa entrada en su lugar.

Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

En las versiones actuales, el error significa que no había ninguna credencial disponible para el proceso worker. Antes de la v2.1.174, una sesión en segundo plano asignada a un worker preinicializado inactivo podía fallar de esta forma incluso cuando había credenciales válidas configuradas. Antes de la v2.1.176, también podía fallar una sesión en la nube que permanecía inactiva antes de ser reclamada. Actualiza para recuperarte.

Qué hacer:

• Actualiza a la v2.1.176 o posterior si esto aparece en una sesión en segundo plano o en la nube y tus credenciales ya están configuradas
• Confirma que ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN o las credenciales de tu proveedor de nube están definidas en el entorno que inicia el worker, no solo en tu shell interactivo
• Para el Agent SDK, consulta la configuración de autenticación en el inicio rápido
• Ejecuta /status en una sesión interactiva en el mismo entorno para confirmar qué fuente de credenciales se resuelve

Clave de API no válida

La variable de entorno ANTHROPIC_API_KEY o el script apiKeyHelper devolvió una clave que la API rechazó, o Claude Code bloqueó una clave de ANTHROPIC_API_KEY antes de enviarla.

Invalid API key · Fix external API key

Cuando el mensaje continúa después de Fix external API key con una descripción como Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines)., la API nunca vio la clave. Claude Code encontró un carácter que los encabezados HTTP no pueden transportar y detuvo la solicitud antes de enviarla. Consulta Valor de encabezado de solicitud no válido para saber cómo leer la descripción y corregir el valor.

Qué hacer:

• Busca errores tipográficos y confirma que la clave no ha sido revocada en la Console
• En el mismo shell, ejecuta env | grep ANTHROPIC, o en PowerShell Get-ChildItem Env:ANTHROPIC*. Herramientas como direnv, los plugins de shell para dotenv y las terminales de los IDE pueden cargar una clave obsoleta desde un archivo .env de tu proyecto sin que la definas explícitamente.
• Elimina ANTHROPIC_API_KEY y ejecuta /login para usar en su lugar la autenticación por suscripción
• Si la clave proviene de un script apiKeyHelper, ejecuta el script directamente para confirmar que imprime una clave válida en stdout
• Ejecuta /status para confirmar qué fuente de credenciales está usando realmente Claude Code

Tu script apiKeyHelper está fallando

Claude Code ejecutó el comando de tu ajuste apiKeyHelper y no obtuvo una clave. Sin ella, la solicitud llega a la API con una credencial de marcador de posición, y la API la rechaza con 401. El panel Authentication de la terminal muestra cuál de estas situaciones ocurrió:

• El comando terminó con un error o se agotó su tiempo de espera
• El comando no imprimió nada en stdout
• El comando imprimió algo además de la clave, como un banner de inicio de sesión o una línea de registro. El panel muestra returned output that cannot be used as an API key e indica qué está mal, sin repetir la salida. Antes de la v2.1.227, Claude Code enviaba lo que el comando imprimiera, tras recortar los espacios en blanco circundantes.

Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

En el modo no interactivo, stderr también incluye el motivo específico, con el prefijo apiKeyHelper failed:.

Claude Code vuelve a ejecutar el script y reintenta la solicitud hasta dos veces más antes de mostrar este mensaje, así que el fallo aparece en un máximo de tres intentos. Antes de la v2.1.208, Claude Code agotaba todo el presupuesto de reintentos reenviando la solicitud con la credencial de marcador de posición y luego informaba un error de autenticación 401 genérico en lugar del fallo del script.

Ejecutar /login no ayuda en este caso: la salida del helper tiene precedencia sobre un inicio de sesión guardado mientras el ajuste esté presente.

Qué hacer:

• Ejecuta directamente en tu shell el comando configurado en apiKeyHelper para reproducir el fallo
• Si el comando informa una sesión expirada, vuelve a autenticarte con tu proveedor de credenciales, por ejemplo iniciando sesión de nuevo en tu SSO o en tu almacén de secretos
• Corrige el comando para que imprima solo la clave en stdout, como un único token de ASCII imprimible de hasta 16,384 caracteres, y termine con el código de salida 0. Consulta rotar credenciales con apiKeyHelper para ver una configuración funcional.
• Ejecuta /status para ver el fallo y confirmar que apiKeyHelper es la fuente de credenciales activa. La fila apiKeyHelper muestra Failing con el detalle del último fallo, como el código de salida y la salida de error del comando, y desaparece después de la siguiente ejecución correcta. Antes de la v2.1.274, /status mostraba solo la fuente de credenciales, no el fallo.
• Cada vez que el comando falla, su código de salida y su salida de error también aparecen en un panel Authentication en la terminal. Antes de la v2.1.212, el panel se titulaba Cloud authentication.

Valor de encabezado de solicitud no válido

Un valor que Claude Code estaba a punto de enviar como encabezado de solicitud contiene un carácter que los encabezados HTTP no pueden transportar: un salto de línea, un byte NUL o un carácter por encima de U+00FF, como una comilla tipográfica o un espacio de ancho cero. Claude Code detiene la solicitud antes de enviar nada e indica la variable o el ajuste que debes corregir. La causa habitual es una credencial pegada desde un documento o un chat que traía un carácter invisible o un salto de línea sobrante.

Claude Code realiza esta comprobación cuando envía solicitudes a la API de Claude directamente o a través de un gateway de LLM. En un proveedor de nube de terceros como Amazon Bedrock, Claude Code no la realiza antes de enviar.

Invalid auth token · Fix external auth token
Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable
Invalid request header from the environment · Fix the environment variable

La primera parte del mensaje depende de dónde provino el valor incorrecto:

• Invalid auth token: un token bearer de ANTHROPIC_AUTH_TOKEN o CLAUDE_CODE_OAUTH_TOKEN
• Invalid ANTHROPIC_CUSTOM_HEADERS: un nombre o valor de encabezado que definiste en ANTHROPIC_CUSTOM_HEADERS. La descripción indica por número qué par Name: Value es el problemático, como distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS, sin repetir el nombre ni el valor, ya que tú elegiste ambos.
• Invalid request header from the environment: un valor que Claude Code copia en un encabezado de solicitud desde otra variable de entorno, como CLAUDE_AGENT_SDK_CLIENT_APP. La descripción indica la variable que debes corregir.

Claude Code informa un ANTHROPIC_API_KEY incorrecto detectado por esta comprobación como Clave de API no válida, con la misma descripción final. En cambio, informa una credencial de /login guardada incorrecta como No has iniciado sesión; ejecuta /login para guardar una nueva. La salida de un script apiKeyHelper nunca llega a esta comprobación: Claude Code la valida cuando se ejecuta el script, y una salida que un encabezado HTTP no puede transportar falla con Tu script apiKeyHelper está fallando.

Después del segundo ·, el mensaje describe el problema, como en este ejemplo completo:

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

Las posiciones cuentan caracteres empezando por uno. La descripción se construye a partir de frases fijas y recuentos de caracteres, así que nunca incluye el valor en sí. Nombra el carácter problemático solo cuando es un carácter invisible o tipográfico conocido, como una marca de orden de bytes, un espacio de ancho cero o una comilla tipográfica, e informa cualquier otro como a non-ASCII character.

Qué hacer:

• Vuelve a definir la variable o el ajuste que indica el mensaje, escribiendo de nuevo a mano los caracteres alrededor de la posición informada en lugar de pegarlos otra vez desde la misma fuente
• Para ANTHROPIC_CUSTOM_HEADERS, mantén un par Name: Value por línea y reescribe el par que indica el mensaje
• Ejecuta /status para confirmar qué fuente de credenciales está activa

Esta organización ha sido deshabilitada

Claude Code está usando un ANTHROPIC_API_KEY obsoleto de una organización de Console deshabilitada. Cuando tienes un inicio de sesión de suscripción guardado, la clave tiene prioridad sobre él.

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
Your ANTHROPIC_API_KEY belongs to a disabled organization · Update or unset the environment variable
API Error: 400 ... This organization has been disabled.

La sugerencia después del · depende de tus credenciales guardadas: la primera forma aparece cuando un /login almacenado puede tomar el relevo después de que elimines la clave, y la segunda cuando la clave es tu única credencial.

Las variables de entorno tienen precedencia sobre /login, así que una clave exportada en tu perfil de shell o cargada desde un archivo .env se usa incluso cuando tienes una suscripción Pro o Max que funciona. En el modo no interactivo (-p), la clave siempre se usa cuando está presente.

Qué hacer:

• Elimina ANTHROPIC_API_KEY en el shell actual y quítala de tu perfil de shell; luego vuelve a iniciar claude
• Si el mensaje dice Update or unset, no tienes ningún inicio de sesión guardado al que recurrir. Elimina la clave y ejecuta /login, o reemplaza la clave por una de una organización de Console activa.
• Ejecuta /status después para confirmar que la credencial activa es tu suscripción
• Si no hay ninguna variable de entorno definida y el error persiste, contacta con soporte o inicia sesión con otra cuenta.

Tu organización ha deshabilitado la autenticación con clave de API

Este mensaje requiere Claude Code v2.1.169 o posterior. El administrador de tu organización de Console ha desactivado la autenticación con clave de API, así que la API rechaza la clave que envía Claude Code. La sugerencia de recuperación después del · varía según el origen de la clave:

Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Sign in again with your claude.ai account

La última forma aparece en una sesión que ejecuta la aplicación Claude Desktop, como la pestaña Code o Cowork, donde vuelves a iniciar sesión desde la aplicación.

Las variables de entorno y apiKeyHelper tienen precedencia sobre /login, así que ejecutar solo /login no ayuda mientras cualquiera de ellos siga proporcionando una clave. Consulta Precedencia de autenticación.

Qué hacer:

• Si el mensaje menciona ANTHROPIC_API_KEY, elimínala en el shell actual y quítala de tu perfil de shell o de tu archivo .env; luego vuelve a iniciar claude
• Si el mensaje menciona apiKeyHelper, quita el ajuste apiKeyHelper de tu settings.json
• Ejecuta /login para iniciar sesión con tu cuenta de claude.ai
• Ejecuta /status después para confirmar que la credencial activa es tu suscripción y no una clave de API
• Si necesitas la autenticación con clave de API para automatización, pide al administrador de tu organización que la vuelva a habilitar en la Console

Tu organización ha deshabilitado el acceso con suscripción de Claude

Tu organización de Claude no permite iniciar sesión en Claude Code con un inicio de sesión de suscripción. Volver a ejecutar /login con la misma cuenta devuelve el mismo error.

Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

Se trata de un ajuste de la organización del lado del servidor, así que no se puede sobrescribir desde la configuración local, las variables de entorno ni los flags de la CLI.

El Agent SDK y el modo no interactivo -p muestran esto como el código de error oauth_org_not_allowed.

Qué hacer:

• Pide a tu administrador que habilite el acceso a Claude Code para tu organización
• Autentícate con una clave de API de Console en lugar de tu suscripción. Consulta Autenticación con Claude Console para configurarla.
• Si eres el administrador y no ves ninguna opción para habilitar el acceso, contacta con el soporte de Anthropic

Las rutinas están deshabilitadas por la política de tu organización

Un Owner de tu organización Team o Enterprise ha desactivado las rutinas a nivel de organización. El error aparece cuando intentas crear o ejecutar una rutina, por ejemplo desde la interfaz de Rutinas en claude.ai/code. En Claude Code v2.1.227 o posterior, el mismo ajuste también oculta /schedule en la CLI.

Routines are disabled by your organization's policy.

Se trata de un ajuste del lado del servidor, así que no se puede sobrescribir desde la configuración local, las variables de entorno ni los flags de la CLI.

Qué hacer:

• Pide a un Owner de tu organización que active el interruptor Routines en claude.ai/admin-settings/claude-code
• Para trabajo programado puntual que no requiere rutinas a nivel de organización, consulta tareas programadas

Remote Control requiere la API de Anthropic

La sesión no se comunica directamente con la API de Anthropic, algo que Remote Control requiere.

Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

Una segunda oración explica qué desvió la sesión de la API de Anthropic; antes de la v2.1.219, el mensaje consistía solo en la primera oración. Según la causa, el mensaje menciona:

• Una variable de proveedor CLAUDE_CODE_USE_*, como CLAUDE_CODE_USE_BEDROCK para Amazon Bedrock o CLAUDE_CODE_USE_VERTEX para Agent Platform de Google Cloud
• ANTHROPIC_BASE_URL apuntando a un host distinto de api.anthropic.com, como un gateway de LLM o un proxy, incluso cuando inicias sesión con claude.ai; antes de la v2.1.196, una URL base personalizada no bloqueaba Remote Control
• ANTHROPIC_UNIX_SOCKET definida, de modo que la sesión envía sus solicitudes a través de un socket local en lugar de a api.anthropic.com
• Un inicio de sesión en un gateway en la nube empresarial realizado mediante /login, que no admite Remote Control y no tiene ninguna variable que eliminar

Qué hacer:

• Elimina la variable que menciona el mensaje, como CLAUDE_CODE_USE_BEDROCK o ANTHROPIC_BASE_URL, y reinicia la sesión, o inicia Remote Control desde una sesión que se comunique directamente con la API de Anthropic
• Si la variable no está definida en tu shell, revisa la clave env en tus archivos de configuración, que aplica variables de entorno a todas las sesiones
• Para este y los demás mensajes de inicio de Remote Control, consulta Solución de problemas de Remote Control

Remote Control no pudo renovar tu inicio de sesión

Claude Code mantiene una conexión de Remote Control activa con credenciales de corta duración que obtiene y renueva usando tu inicio de sesión de claude.ai guardado. Cuando claude.ai deja de aceptar ese inicio de sesión, o Claude Code ya no tiene ningún inicio de sesión guardado, Claude Code detiene Remote Control y necesita que vuelvas a iniciar sesión. Cualquiera de los dos fallos puede ocurrir mientras Claude Code todavía se está conectando o más tarde, cuando renueva las credenciales.

Cuando Claude Code pide al servicio de inicio de sesión que renueve tu inicio de sesión guardado y no obtiene respuesta, mantiene Remote Control en funcionamiento y vuelve a intentar la renovación mientras la credencial actual de la conexión siga siendo válida. Una renovación no obtiene respuesta cuando Claude Code no puede llegar al servicio de inicio de sesión, se agota el tiempo de espera de la solicitud o el servicio falla sin rechazar tu inicio de sesión. Si el servicio de inicio de sesión sigue sin responder cuando esa credencial expira, Claude Code detiene Remote Control e informa OAuth token refresh failed.

Cuando Claude Code detiene Remote Control, muestra el motivo en una advertencia y en una línea de la transcripción que empieza por Remote Control disconnected. Tu sesión local sigue ejecutándose sin Remote Control. Esta sección cubre estas líneas:

Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control
Remote Control disconnected — Claude.ai login was rejected — run /login, then /remote-control
Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control
Remote Control disconnected — OAuth token refresh failed — run /login to re-authenticate
Remote Control disconnected — JWT refresh failed: no OAuth token — run /login
Remote Control disconnected — Signed out of Claude — run /login, then /remote-control

Claude Code indica la causa en la parte central del mensaje:

• Claude.ai login expired y Claude.ai login was rejected: claude.ai ya no acepta tu token de inicio de sesión guardado, porque expiró o fue revocado
• OAuth token unavailable: Claude Code no tenía ningún token de inicio de sesión guardado cuando correspondía renovar la credencial de la conexión
• OAuth token refresh failed: claude.ai rechazó tu token de inicio de sesión guardado mientras Claude Code se reconectaba, y la renovación del token no produjo uno nuevo
• JWT refresh failed: no OAuth token: Claude Code no encontró ningún token de inicio de sesión guardado con el que renovar
• Signed out of Claude: cerraste sesión en esta máquina, por ejemplo ejecutando /logout en otra terminal, así que Claude Code no tiene ningún inicio de sesión guardado con el que renovar la conexión

Qué hacer:

• Ejecuta /login para volver a iniciar sesión
• Ejecuta /remote-control para reconectar la sesión. Los mensajes que terminan en run /login to restore Remote Control no necesitan este paso: Claude Code se reconecta por sí solo una vez que inicias sesión.

Antes de la v2.1.224, OAuth token refresh failed — run /login to re-authenticate decía OAuth token refresh failed — re-authenticate, then re-enable Remote Control, y JWT refresh failed: no OAuth token — run /login decía no OAuth token available for recovery (code <N>). Los mensajes Claude.ai login expired, Claude.ai login was rejected y OAuth token unavailable se añadieron en la v2.1.225.

Antes de la v2.1.238, Claude Code informaba los casos que ahora dicen Signed out of Claude como JWT refresh failed: no OAuth token — run /login, y detenía Remote Control con Claude.ai login expired — run /login to restore Remote Control en cuanto una renovación del inicio de sesión no obtenía respuesta.

Remote Control se detuvo porque cambió la cuenta con la que iniciaste sesión

Claude Code muestra esta línea durante una sesión de Remote Control cuando inicias sesión en otra cuenta u organización de claude.ai en esta máquina. Hiciste el cambio fuera de la sesión de Claude Code, por ejemplo ejecutando /login en otra terminal.

Una sesión de Remote Control que iniciaste con una sesión abierta mediante /login pertenece a la cuenta y la organización de claude.ai con las que tenías la sesión iniciada en ese momento.

Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

Claude Code detiene la sesión de Remote Control en cuanto claude.ai confirma que la cuenta o la organización cambió. Tu sesión local sigue ejecutándose sin Remote Control.

Qué hacer:

• Ejecuta /remote-control para iniciar una nueva sesión de Remote Control con la cuenta u organización actual
• Para volver a la anterior, ejecuta /login e inicia sesión de nuevo en la cuenta u organización anterior. Luego ejecuta /remote-control.

Antes de la v2.1.234, Claude Code no detectaba cuándo cambiabas a otra cuenta u organización fuera de la sesión de Claude Code. Claude Code mantenía conectada la sesión de Remote Control hasta que una solicitud posterior al servidor de Remote Control fallaba con Remote Control server rejected the request (HTTP 404). Ese fallo podía producirse horas después del cambio.

Remote Control se detuvo porque la aplicación que ejecuta la sesión cerró sesión o cambió de cuenta

Cuando la aplicación de escritorio de Claude o un IDE aloja tu sesión, Claude Code obtiene su token de inicio de sesión de esa aplicación en lugar de /login. Cuando claude.ai rechaza ese token, Claude Code pide uno nuevo a la aplicación. Si la aplicación responde que no tiene la sesión iniciada, o que ahora tiene la sesión iniciada en otra cuenta de Claude, Claude Code finaliza la sesión de Remote Control y envía a la aplicación una de estas líneas:

Remote Control stopped — the app running this session is now signed in to a different Claude account
Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on

Tu sesión local sigue ejecutándose sin Remote Control.

Qué hacer:

• Si la aplicación cerró sesión, vuelve a iniciar sesión en ella y luego reactiva Remote Control en la aplicación
• Si la aplicación cambió de cuenta, Claude Code no puede continuar la sesión finalizada con la nueva cuenta. Inicia una nueva sesión de Remote Control con esa cuenta.

Antes de la v2.1.238, Claude Code enviaba a la aplicación los mensajes run /login enumerados en Remote Control no pudo renovar tu inicio de sesión en ambos casos.

Token de OAuth revocado o expirado

Tu inicio de sesión guardado ya no es válido. Un token revocado significa que cerraste sesión en todas partes o que un administrador eliminó el acceso; un token expirado significa que la renovación automática falló a mitad de la sesión.

Ambos mensajes informan un rechazo que la API devolvió para una solicitud que envió Claude Code. Cuando el inicio de sesión guardado ya se ha borrado tras una renovación fallida, ves Inicio de sesión expirado en su lugar. Si te autenticas con un token de larga duración en CLAUDE_CODE_OAUTH_TOKEN, ves los mismos mensajes cuando ese token expira o se revoca.

OAuth token revoked · Please run /login
Please run /login · API Error: 401 OAuth token has expired ...

En el modo no interactivo (-p) y en el Agent SDK, los mensajes dicen lo siguiente, y el código de error estructurado es authentication_failed:

Failed to authenticate: OAuth token revoked. Please log in again or contact your administrator.
Failed to authenticate. API Error: 401 OAuth token has expired ...

Antes de la v2.1.287, en el modo no interactivo y en el Agent SDK, el mensaje de token revocado decía Your account does not have access to Claude. Please login again or contact your administrator.

Qué hacer:

• Ejecuta /login en el prompt de Claude Code para volver a iniciar sesión
• Si tu comando -p o tu programa del Agent SDK usa un inicio de sesión guardado, ejecuta claude en el mismo entorno, completa /login y luego vuelve a ejecutar el comando o el programa. Para automatización que no puede iniciar sesión de forma interactiva, autentícate con ANTHROPIC_API_KEY o genera un token de larga duración con claude setup-token.
• Si te autenticas con la variable de entorno CLAUDE_CODE_OAUTH_TOKEN, Claude Code sigue enviando el valor que definiste después de que una solicitud falle con un 401, en lugar de cambiar al token de un inicio de sesión almacenado. /status muestra esta credencial como una fila Auth token que dice CLAUDE_CODE_OAUTH_TOKEN. Genera un token nuevo con claude setup-token y reinicia con él, o elimina la variable y ejecuta /login. Antes de la v2.1.225, Claude Code podía reemplazar el valor de la variable a mitad de la sesión con el token de acceso de corta duración de un inicio de sesión almacenado, y la sesión volvía a fallar con errores 401 una vez que ese token expiraba.
• Si se te pide iniciar sesión repetidamente entre ejecuciones, consulta las comprobaciones del reloj del sistema y los pasos de recuperación del almacenamiento de credenciales en macOS en Solución de problemas
• Para otros fallos, incluidos 403 Forbidden y problemas de OAuth en el navegador, consulta Inicio de sesión y autenticación

API Error: 401 Invalid authentication credentials

La API reconoció el formato de tu credencial pero rechazó la cuenta o la organización asociada. Anthropic devuelve este mensaje cuando una credencial se revocó recientemente, cuando una organización se deshabilitó o eliminó tu acceso, o cuando la propia cuenta se desactivó, así que la causa no es un token expirado. La credencial puede ser tu inicio de sesión guardado o un ANTHROPIC_API_KEY aprobado, y la solución es distinta en cada caso, así que empieza ejecutando /status para ver cuál está activa.

Please run /login · API Error: 401 Invalid authentication credentials

Qué hacer:

• Si /status muestra una fila API key que no está marcada como no en uso, un ANTHROPIC_API_KEY aprobado es la credencial activa y tiene precedencia sobre tu inicio de sesión, así que /login no lo reemplaza. Rota la clave en Claude Console, o vuelve a tu suscripción ejecutando unset ANTHROPIC_API_KEY, o en PowerShell Remove-Item Env:ANTHROPIC_API_KEY.
• Si /status muestra solo tu inicio de sesión, ejecuta /login una vez. Si la credencial se revocó, un nuevo inicio de sesión la reemplaza.
• Si el mismo mensaje vuelve a aparecer con la misma cuenta de inicio de sesión, la cuenta o la organización ya no está activa. Comprueba la cuenta y la organización que informa /status, y pide al administrador de tu organización que restaure el acceso.
• Si ANTHROPIC_BASE_URL apunta a un gateway de LLM, el texto después de 401 es el mensaje de tu gateway y no el de Anthropic, y /login no lo cambia. Corrige en su lugar la credencial que espera tu gateway.

Inicio de sesión expirado

Claude Code intentó renovar tu inicio de sesión de claude.ai guardado y el servicio de OAuth rechazó el token de renovación almacenado, así que Claude Code borró las credenciales guardadas. A partir de ese momento, cada solicitud al modelo se detiene localmente con este mensaje antes de llegar a la API, porque solo /login puede crear credenciales nuevas.

Antes de la v2.1.206, Claude Code enviaba la solicitud al modelo de todos modos con la credencial que quedara en el entorno, y entonces todos los modelos fallaban con Hay un problema con el modelo seleccionado o con un 401 en lugar de pedirte que iniciaras sesión.

Login expired · Please run /login

En el modo no interactivo (-p) y en el Agent SDK, el mensaje dice lo siguiente, y el código de error estructurado es authentication_failed:

Failed to authenticate: OAuth session expired and could not be refreshed

Este no es el mismo estado que Token de OAuth revocado o expirado. Esos mensajes informan un rechazo que devolvió la API. Claude Code genera por sí mismo Login expired para un inicio de sesión que ya no logró renovar, así que no envía ninguna solicitud. Cuando la renovación falla porque la propia cuenta está suspendida y no porque el inicio de sesión esté obsoleto, Claude Code muestra Tu cuenta está en espera en su lugar.

Las sesiones autenticadas con una clave de API, CLAUDE_CODE_OAUTH_TOKEN o un proveedor de terceros no usan el inicio de sesión guardado y nunca ven este mensaje.

Puedes comprobar este estado antes de que falle una solicitud: /status muestra una fila Login que dice Expired — log in again, junto con la organización y el correo electrónico que tiene guardados para el inicio de sesión expirado. La fila aparece solo cuando el inicio de sesión guardado es tu credencial activa y ya no se puede renovar. Las sesiones autenticadas de otra forma no muestran la fila, aunque siga guardado un inicio de sesión expirado. Antes de la v2.1.210, /status no daba ninguna indicación en este estado de que alguna vez hubiera existido un inicio de sesión, porque la credencial borrada no le dejaba nada que informar.

Qué hacer:

• Ejecuta /login para volver a iniciar sesión. Reintentar sin iniciar sesión muestra el mismo mensaje en cada solicitud.
• Si inicias sesión con tu cuenta de claude.ai en otra ventana de Claude Code, consulta No has iniciado sesión para saber cuándo esta sesión empieza a usar ese inicio de sesión por sí sola.
• En el modo no interactivo, ejecuta claude en el mismo entorno, completa /login y luego vuelve a ejecutar tu comando. Para automatización que no puede iniciar sesión de forma interactiva, autentícate con ANTHROPIC_API_KEY o genera un token de larga duración con claude setup-token.
• Si el inicio de sesión sigue fallando, consulta Inicio de sesión y autenticación

No se pudo renovar tu inicio de sesión porque otro proceso de Claude Code lo está renovando

Este mensaje no significa que se rechazara tu inicio de sesión. Tu inicio de sesión de claude.ai guardado había expirado y necesitaba renovarse. Otro proceso de Claude Code en la misma máquina tenía el bloqueo de renovación compartido, o terminó y lo dejó tomado, y la renovación no avanzó mientras esta sesión esperaba. Claude Code detiene la solicitud antes de enviarla:

Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login

En el modo no interactivo (-p) y en el Agent SDK, el mensaje dice lo siguiente, y el código de error estructurado es server_error:

Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

Las sesiones autenticadas con una clave de API, CLAUDE_CODE_OAUTH_TOKEN o un proveedor de terceros no usan el inicio de sesión guardado y nunca ven este mensaje.

Qué hacer:

• Vuelve a intentarlo en un minuto. Si otro proceso completa antes la renovación, esta sesión usa el inicio de sesión renovado.
• Si el mensaje sigue apareciendo, cierra las demás ventanas y procesos de Claude Code y luego reintenta.
• Si vuelve a aparecer sin ningún otro proceso de Claude Code en ejecución, ejecuta /login. Volver a iniciar sesión no espera al bloqueo de renovación.

No se pudo guardar tu inicio de sesión

Iniciaste sesión con claude.ai, pero Claude Code no pudo guardar el inicio de sesión en su almacén de credenciales, así que el inicio de sesión no se completó. En macOS esto puede ocurrir cuando el llavero de inicio de sesión se bloquea, por ejemplo al entrar en reposo o por inactividad, después de que Claude Code ya haya leído o guardado credenciales en él durante la misma sesión.

Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.
Couldn't save your login. Try logging in again.

La primera forma aparece en macOS y la segunda en todos los demás sistemas. Un fallo transitorio del almacén de credenciales, como un tiempo de espera agotado o un almacén ilegible, produce el mismo mensaje.

Qué hacer:

• En macOS, desbloquea el llavero de inicio de sesión y luego vuelve a ejecutar /login
• En otras plataformas, vuelve a ejecutar /login
• Si el inicio de sesión sigue sin guardarse, consulta No has iniciado sesión o el token expiró para ver el comando para desbloquear el llavero y otros pasos de recuperación del almacenamiento de credenciales

No se pudo iniciar el servidor de callback de OAuth

Cuando /login, claude auth login o claude setup-token te inician sesión a través del navegador, Claude Code abre un puerto de escucha en 127.0.0.1 para que tu navegador pueda devolverle el resultado del inicio de sesión. Este mensaje significa que Claude Code no pudo abrir ese puerto, y el inicio de sesión se detiene antes de que aparezca una ventana del navegador o una URL de inicio de sesión:

Failed to start OAuth callback server: Failed to start server. Is port 0 in use?

Si tu mensaje termina en Is port 0 in use?, el intento de escuchar en la dirección de loopback IPv4 127.0.0.1 falló por completo. Como el fallo ocurre antes de que exista una URL de inicio de sesión, el flujo Paste code here if prompted no está disponible como alternativa.

Qué hacer:

• Para iniciar sesión de inmediato sin el listener local: si usas una suscripción de claude.ai, ejecuta claude setup-token en una máquina donde el inicio de sesión funcione y define el token que imprime como CLAUDE_CODE_OAUTH_TOKEN en esta máquina. De lo contrario, define ANTHROPIC_API_KEY con una clave de Claude Console. Precedencia de autenticación explica cómo elige Claude Code entre credenciales.
• Para usar en su lugar el inicio de sesión por navegador en esta máquina, Claude Code debe poder escuchar en 127.0.0.1. Si se ejecuta dentro de un sandbox, comprueba que la política del sandbox permita escuchar en puertos locales y luego vuelve a ejecutar /login. Si debería poder hacerlo y sigue fallando, ejecuta /feedback para que el informe incluya los detalles de tu entorno.

Inicio de sesión de Claude no aceptado

Intentaste iniciar una sesión en la nube, y el servidor se negó a crearla con un 401: no aceptó el inicio de sesión de Claude que envió esta máquina, normalmente porque el inicio de sesión expiró o fue revocado.

La primera parte de la línea es el motivo propio del servidor cuando lo proporciona. De lo contrario, la línea dice:

Claude login not accepted · Run /login, then try again

Qué hacer:

• Ejecuta /login, completa el inicio de sesión y luego vuelve a iniciar la sesión

Los artefactos necesitan un inicio de sesión de claude.ai

Claude Code rechazó la publicación o lectura de un artefacto porque la sesión no tiene ningún inicio de sesión de claude.ai que pueda usar para artefactos.

Todas las formas del mensaje empiezan con las mismas palabras, seguidas de una solución que depende de cómo se autentica tu sesión. Sin ninguna credencial en conflicto, dice:

Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.

Qué hacer:

• Ejecuta /login y selecciona Claude account with subscription. La opción Anthropic Console account no proporciona credenciales de claude.ai.
• Cuando el mensaje menciona una credencial que tiene precedencia, como ANTHROPIC_API_KEY, un ajuste apiKeyHelper o una clave de Console guardada por un /login anterior, quítala como indica el mensaje y luego ejecuta /login
• Cuando el mensaje dice que esta sesión remota se autentica a través de la máquina que la inició, inicia sesión en claude.ai en esa máquina y luego reconecta la sesión
• Cuando el mensaje dice que la credencial la inyecta el entorno anfitrión de la sesión, no puedes cambiarla en esa sesión; inicia una sesión que tenga la sesión de claude.ai iniciada
• Consulta Disponibilidad para ver los demás requisitos de los artefactos, como el plan, el proveedor del modelo y la política de la organización

La política del administrador requiere un inicio de sesión en el gateway en la nube

La configuración administrada de un administrador en esta máquina establece forceLoginMethod en "gateway" o define forceLoginGatewayUrl. A menos que selecciones un proveedor de nube mediante una variable como CLAUDE_CODE_USE_BEDROCK, Claude Code acepta entonces solo el inicio de sesión del gateway de aplicaciones de Claude. Ves uno de dos mensajes:

Not signed in to the Cloud gateway — run /login.

Las solicitudes al modelo fallan con este mensaje cuando la sesión no tiene un inicio de sesión en el gateway, por ejemplo porque no has ejecutado /login desde que la política llegó a la máquina.

Si la máquina también tiene una credencial emitida por Anthropic y la configuración administrada establece forceLoginMethod o forceLoginOrgUUID, Claude Code termina al inicio en su lugar. Esa credencial puede ser una variable ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN, un ajuste apiKeyHelper o una clave de API guardada por un inicio de sesión anterior en Claude Console.

El mensaje de inicio indica la credencial con la que está configurada la sesión, dónde está definida y el paso para quitarla. Por ejemplo, con una variable ANTHROPIC_API_KEY definida en tu shell, dice:

Administrator policy requires a Cloud gateway sign-in on this machine, but this session is configured with an API key from ANTHROPIC_API_KEY, which a gateway machine does not accept.

To continue: unset ANTHROPIC_API_KEY (or run in a shell without it), then run claude and sign in with /login.

Qué hacer:

• Para Not signed in to the Cloud gateway, ejecuta /login y completa el inicio de sesión en la pantalla Cloud gateway
• Para el mensaje de inicio, quita la credencial siguiendo los pasos que aparecen al final del mensaje
• Si crees que la máquina no debería requerir el gateway, pide al administrador que la gestiona que quite forceLoginMethod y forceLoginGatewayUrl de su configuración administrada

Antes de la v2.1.284, el mensaje de inicio enumeraba las credenciales posibles en lugar de nombrar la configurada. Empezaba con Administrator policy requires a Cloud gateway sign-in on this machine; the Anthropic-issued credential configured here (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used. Si ves ese texto y no puedes saber qué credencial quitar, actualiza a la v2.1.284 o posterior y vuelve a iniciar claude.

En la v2.1.265, una regresión también mostraba el primer mensaje en algunas configuraciones de gateway de LLM y de proxy que se autentican con una clave de API, apiKeyHelper o encabezados personalizados, incluso sin ningún requisito del administrador en la máquina. Actualiza a la v2.1.266 o posterior. No necesitas cambiar tu configuración.

Antes de la v2.1.261, en máquinas que establecían forceLoginMethod en "gateway", Claude Code usaba un inicio de sesión guardado sobrante en lugar de hacer fallar las solicitudes al modelo, e informaba una credencial de entorno configurada con This machine's managed settings require a first-party login en lugar del mensaje de inicio.

Tu cuenta está en espera

La cuenta de Claude asociada a tu inicio de sesión ha sido suspendida. Claude Code muestra el primer mensaje cuando intenta renovar tu inicio de sesión guardado y se entera de la suspensión, y el segundo cuando lo informa un inicio de sesión que completas en el navegador:

Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

Volver a iniciar sesión con la misma cuenta no elimina el mensaje, porque la suspensión afecta a la cuenta y no al inicio de sesión. En el modo no interactivo (-p) y en el Agent SDK, el código de error estructurado es account_on_hold. Antes de la v2.1.235, Claude Code informaba una cuenta en espera como Login expired · Please run /login, cuyos pasos de recuperación no pueden eliminar una suspensión.

Qué hacer:

• Abre el enlace del mensaje para ver los detalles de la suspensión o apelarla
• Si tienes otra cuenta de Claude o una clave de API que no se ve afectada por la suspensión, puedes seguir trabajando mientras se resuelve: ejecuta /login con esa cuenta, o define la clave con ANTHROPIC_API_KEY

Inicio de sesión del perfil de Anthropic expirado

Claude Code se está autenticando mediante un perfil de credenciales de Anthropic cuya credencial de inicio de sesión guardada ha expirado, y el perfil no contiene ninguna credencial de renovación que Claude Code pueda usar para renovarla. Claude Code detiene cada solicitud localmente sin reintentar, porque un reintento leería la misma credencial expirada.

Anthropic profile login expired · Re-authenticate your Anthropic profile
Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

Esto aparece solo cuando la credencial activa proviene de un perfil de credenciales de Anthropic: uno que seleccionas con la variable de entorno ANTHROPIC_PROFILE, que Claude Code descubre como el perfil activo en tu directorio de configuración de Anthropic, o que Claude Code escribió cuando iniciaste sesión sin una clave de API. Las sesiones que se autentican con una clave de API, un token bearer como ANTHROPIC_AUTH_TOKEN o un proveedor de terceros nunca ven este mensaje.

En una máquina que ofrece el inicio de sesión sin clave, ejecuta /login, elige la cuenta de Anthropic Console y vuelve a iniciar sesión para renovar un perfil que escribió el inicio de sesión sin clave de Console o el ant auth login de la CLI de Claude Platform. Claude Code reemplaza la credencial expirada en ese perfil. Para un perfil de federación o uno creado por otra herramienta, /login no renueva la credencial. La forma que ves depende de si seleccionaste el perfil o si Claude Code lo descubrió:

• Cuando defines ANTHROPIC_PROFILE explícitamente, el mensaje termina con Re-authenticate your Anthropic profile.
• Cuando Claude Code descubrió el perfil en tu directorio de configuración, el mensaje ofrece /login, porque Claude Code da a un /login que funcione precedencia sobre el perfil descubierto y entonces se autentica con tu cuenta de claude.ai o de Console en su lugar. Antes de la v2.1.234, Claude Code también mostraba la forma Re-authenticate your Anthropic profile en este caso.

Qué hacer:

• Vuelve a iniciar sesión en el perfil y luego reintenta: en una máquina que ofrece el inicio de sesión sin clave, ejecuta /login y elige la cuenta de Anthropic Console para un perfil que escribió el inicio de sesión sin clave de Console o el ant auth login de la CLI de Claude Platform; para otros perfiles, usa la herramienta que los creó
• Si un administrador aprovisionó la credencial del perfil, pídele que emita una nueva
• Ejecuta /status para confirmar la fuente de credenciales activa y el nombre del perfil
• Para dejar de usar el perfil, elimina ANTHROPIC_PROFILE si la definiste y luego autentícate de otra forma, como /login o ANTHROPIC_API_KEY

Requisito de alcance de OAuth

El token almacenado es anterior a un alcance de permisos que necesita una función más reciente:

OAuth token does not meet scope requirement: user:profile

Qué hacer:

• Ejecuta /login para obtener un token nuevo con los alcances actuales. No necesitas cerrar sesión primero.

claude.ai rechazó el token de sesión

Una solicitud de un conector de claude.ai falló porque claude.ai rechazó el token de tu inicio de sesión de Claude Code. El token rechazado es tu inicio de sesión, no la autorización propia del conector en claude.ai, así que volver a autorizar el conector no lo resuelve. En /mcp, el conector aparece como session token rejected y su vista de detalles dice:

claude.ai rejected the session token. Run /login, then reconnect.

Qué hacer:

• Ejecuta /login para volver a iniciar sesión
• Reconecta el conector desde /mcp, o ejecuta /mcp reconnect <server>. Reconectar antes de volver a iniciar sesión deja el conector en el mismo estado. La opción Reconnect del panel de /mcp informa your claude.ai session token was rejected; la forma escrita /mcp reconnect <server> informa una reconexión correcta aunque el token siga rechazado.

Antes de la v2.1.222, Claude Code marcaba en su lugar el conector como pendiente de autenticación, lo que te dirigía al flujo de autorización del conector aunque completarlo no resolvía el estado.

El servidor MCP necesita que vuelvas a iniciar sesión

Un servidor MCP remoto rechazó la credencial en una llamada a herramienta a mitad de la sesión, normalmente porque un inicio de sesión o un token expiró o porque el token carece de un permiso que la herramienta necesita. La llamada a herramienta falla, y /mcp marca el servidor como pendiente de autenticación.

Para un servidor en el que inicias sesión desde Claude Code, incluido un conector de claude.ai, el inicio de sesión expiró o fue revocado:

MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)

Ejecuta /mcp, selecciona el servidor y vuelve a iniciar sesión desde su menú.

Para un servidor configurado con un script headersHelper, Claude Code ya ha vuelto a ejecutar el helper y reintentado la llamada una vez antes de mostrar esto:

MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)

Comprueba que el helper devuelve una credencial que el servidor acepta y luego reconecta desde /mcp, lo que vuelve a ejecutar el helper.

Para un servidor con un encabezado Authorization estático en su configuración:

MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)

Actualiza el valor del encabezado donde está configurado el servidor y luego reconecta desde /mcp.

Antes de la v2.1.273, los casos de inicio de sesión expirado, headersHelper y encabezado Authorization mostraban todos MCP server "<name>" requires re-authorization (token expired).

Un servidor también puede rechazar una llamada a herramienta con HTTP 403 insufficient_scope para pedirte que autorices un alcance, a veces uno que tu token ya incluye. El mensaje nombra ese alcance:

MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

Ejecuta /mcp, selecciona el servidor y vuelve a autenticarte desde su menú.

Cuando la configuración del servidor no define ni oauth.scopes ni authServerMetadataUrl, Claude Code solicita el alcance que nombró el servidor. Con cualquiera de esos ajustes, Claude Code solicita en su lugar los alcances de ese ajuste. Si fijaste oauth.scopes, añade el alcance que falta a esa lista antes de volver a autenticarte.

Antes de la v2.1.274, este caso mostraba el mensaje needs you to sign in again, y antes de la v2.1.273 mostraba requires re-authorization (token expired) como los demás casos.

Falta la URL del servidor MCP o no es una URL válida

Claude Code se negó a iniciar un inicio de sesión de OAuth para un servidor MCP remoto porque la url configurada del servidor no se puede analizar como URL. A menos que Claude Code tenga un problema de configuración más específico que informar para el servidor, ejecutar claude mcp login <name> en tu shell imprime el rechazo así:

Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.

Qué hacer:

• Establece la url de la entrada en el endpoint real del servidor donde está configurado el servidor, o define la variable de entorno que nombra su referencia ${VAR}, y luego vuelve a ejecutar el inicio de sesión.

Discrepancia del emisor en la respuesta de autorización

Durante un inicio de sesión de OAuth de MCP, el servidor de autorización redirigió de vuelta a Claude Code con un parámetro iss que no nombra el emisor que Claude Code esperaba según los metadatos de OAuth del servidor. Un emisor incorrecto en este paso es el aspecto que tiene un ataque de confusión de servidores de autorización (mix-up), así que Claude Code hace fallar el inicio de sesión en lugar de intercambiar el código de autorización. Claude Code muestra el error en el menú del servidor de /mcp después del inicio de sesión en el navegador:

Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

expected es el emisor de los metadatos de OAuth del servidor, y received es el valor de iss que traía la redirección. Un inicio de sesión cuya redirección no incluye ningún parámetro iss pasa la comprobación, a menos que los metadatos del servidor establezcan authorization_response_iss_parameter_supported, en cuyo caso Claude Code hace fallar el inicio de sesión.

Qué hacer:

• Vuelve a intentar el inicio de sesión desde /mcp
• Si el error se repite, infórmalo al operador del servidor. La solución es del lado del servidor: el servidor de autorización debe devolver en el parámetro iss el mismo emisor que anuncia en sus metadatos
• Para conectarte mientras se corrige el servidor, inicia Claude Code con MCP_SDK_GENERATION=v1, cuyo runtime no realiza esta comprobación. Esto elimina una protección contra los ataques de confusión, así que es preferible la solución del lado del servidor

Antes de la v2.1.232, Claude Code usaba el runtime v2 solo en un despliegue gradual o cuando definías MCP_SDK_GENERATION=v2.

Se rechaza enviar credenciales a un endpoint de token que no es https

En el runtime v2, Claude Code envía una solicitud de token de OAuth de MCP solo a un endpoint de token servido por HTTPS o en localhost, 127.0.0.1 o ::1. Este mensaje significa que el endpoint de token del servidor no es ninguna de esas opciones, así que Claude Code se detuvo antes de enviar la solicitud. Eso ocurre después del inicio de sesión en el navegador, así que el paso del navegador se completa primero, y de nuevo cada vez que Claude Code renueva el token del servidor.

En su forma completa, el mensaje proviene del MCP SDK y cita el endpoint de token que rechazó. En el registro de depuración, aparece después de Error during auth completion: para un inicio de sesión o de Token refresh failed: para una renovación. En tu shell, claude mcp login <name> lo imprime después de Couldn't complete authentication for "<name>":, y en una sesión, /mcp lo muestra en el menú del servidor:

Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

Claude Code trata como posiblemente secreta una URL de servidor que tiene una cadena de consulta o un segmento de ruta largo de aspecto aleatorio. Para un servidor así, oculta los errores de inicio de sesión que genera el MCP SDK antes de mostrarlos o registrarlos. Este error aparece entonces como un nombre corto que puede cambiar entre versiones, como io, seguido de from the MCP SDK for y la URL del servidor ocultada. Otros errores del MCP SDK adoptan la misma forma ahí. El mensaje ocultado solo puede corresponder a este error cuando el endpoint de token del servidor es http:// simple en una dirección distinta de localhost, 127.0.0.1 o ::1.

Qué hacer:

• Sirve ese endpoint de token por HTTPS, por ejemplo colocando el servidor detrás de un proxy inverso o un túnel que termine TLS y configurando el servidor para que anuncie la dirección https://
• Para conectarte sin cambiar el servidor, inicia Claude Code con MCP_SDK_GENERATION=v1, cuyo runtime no aplica esta regla y envía la solicitud de token por HTTP simple. Esa elección dura hasta que sales y se aplica a todos los servidores. El runtime v1 también omite la comprobación del emisor, así que es preferible servir el endpoint por HTTPS

Credenciales de AWS expiradas o no válidas

Tu token de sesión de AWS expiró o fue rechazado. Este mensaje aparece ante un 401 de Claude Platform on AWS o del endpoint de Mantle, que es como esos proveedores informan un token de seguridad expirado.

La sugerencia de acción de la parte central varía según tu configuración. La parte estable es el AWS credentials expired or invalid inicial:

AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

Antes de la v2.1.273, este mensaje aparecía solo cuando awsAuthRefresh estaba configurado.

Qué hacer:

• Si la sugerencia dice que las credenciales las gestiona este entorno, la aplicación que inició Claude Code es dueña de la credencial y los demás pasos de esta sección no se aplican: reintenta o contacta con tu administrador
• Si awsAuthRefresh está definido, ejecuta en otra terminal el comando que indica el mensaje, como aws sso login --profile myprofile, completa el inicio de sesión en el navegador y luego reintenta. De lo contrario, renueva tú mismo la credencial de AWS que usas: tu inicio de sesión de SSO, tus claves de acceso, tu clave de API o tu token de proxy
• Con awsAuthRefresh definido en una sesión interactiva, puedes en su lugar ejecutar /login, elegir 3rd-party platform y luego seleccionar Claude Platform on AWS · refresh credentials en Using 3rd-party platforms para ejecutar el mismo comando sin reiniciar Claude Code. Consulta Configurar las credenciales de AWS
• Si el error se repite después de que el comando de renovación se complete correctamente, confirma que la identidad es válida fuera de Claude Code con aws sts get-caller-identity en el mismo shell y perfil

Falló la autenticación de AWS

Tu proveedor de AWS devolvió un 403, o Amazon Bedrock devolvió un 401.

Amazon Bedrock informa un token de seguridad expirado como un 403, pero un 403 también es la forma en que informa una denegación de autorización, como un AccessDeniedException por falta de un permiso de IAM. Claude Code no puede distinguir entre esas dos causas.

Un 401 de Amazon Bedrock también llega aquí y no a Credenciales de AWS expiradas o no válidas, porque Amazon Bedrock no informa un token expirado como un 401. Un 401 de ese endpoint suele provenir de algo más en la ruta de la solicitud, como un proxy corporativo.

Una renovación de credenciales soluciona un token expirado pero no puede solucionar las demás causas, así que el mensaje ofrece ambas opciones:

AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

La sugerencia de acción de la parte central varía según tu configuración. La parte estable es el AWS authentication failed inicial.

Cuando el 403 es la respuesta de Amazon Bedrock indicando que no tienes acceso al modelo con el ID de modelo especificado, la sugerencia te indica en su lugar que habilites el modelo para tu cuenta y región en la consola de Amazon Bedrock.

Antes de la v2.1.273, este mensaje aparecía solo cuando awsAuthRefresh estaba configurado.

Qué hacer:

• Si la sugerencia dice que las credenciales las gestiona este entorno, la aplicación que inició Claude Code es dueña de la credencial y los demás pasos de esta sección no se aplican: reintenta o contacta con tu administrador
• Renueva tus credenciales de AWS por si la causa es una credencial expirada: ejecuta el comando awsAuthRefresh que indica el mensaje cuando hay uno definido, o renueva tú mismo tu inicio de sesión de SSO, tus claves de acceso, tu clave de API o tu token de proxy
• Si tus credenciales están al día, confirma que los permisos de IAM de Configuración de IAM están asociados a la identidad que usas y que el modelo seleccionado está habilitado para tu cuenta y región
• Ejecuta aws sts get-caller-identity para confirmar qué identidad usan tus solicitudes

Credenciales de Google Cloud expiradas o no válidas

Tus credenciales de Google Cloud para Agent Platform de Google Cloud expiraron o fueron rechazadas: la solicitud devolvió un 401, que es como Agent Platform informa la expiración de credenciales.

La sugerencia de acción de la parte central varía según tu configuración. La parte estable es el Google Cloud credentials expired or invalid inicial:

Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...

Qué hacer:

• Si la sugerencia dice que las credenciales las gestiona este entorno, la aplicación que inició Claude Code es dueña de la credencial y los demás pasos de esta sección no se aplican: reintenta o contacta con tu administrador
• Si te autenticas con las credenciales predeterminadas de la aplicación, ejecuta el comando gcpAuthRefresh que indica el mensaje, o gcloud auth application-default login, completa el inicio de sesión y luego reintenta
• Si enrutas a través de un gateway de LLM con CLAUDE_CODE_SKIP_VERTEX_AUTH definida, renueva el token del gateway en ANTHROPIC_AUTH_TOKEN o ANTHROPIC_CUSTOM_HEADERS y luego reintenta
• Si te autenticas con un archivo de clave de cuenta de servicio, confirma que GOOGLE_APPLICATION_CREDENTIALS apunta a una clave válida. Consulta Configurar las credenciales de GCP
• Si el error se repite después de una renovación, confirma que la identidad funciona fuera de Claude Code con gcloud auth application-default print-access-token en el mismo shell

Antes de la v2.1.273, un 401 de Agent Platform mostraba en su lugar el mensaje genérico Please run /login o Failed to authenticate, que no puede renovar las credenciales de Google Cloud.

Falló la autenticación de Google Cloud

Agent Platform de Google Cloud devolvió un 403, que usa para denegaciones de autorización en lugar de credenciales vencidas. Por lo general, a la identidad con la que te autenticas le falta un permiso de IAM, o el modelo no está habilitado para tu proyecto.

La sugerencia de acción en la parte central varía según tu configuración. La parte estable es el Google Cloud authentication failed inicial:

Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...

Qué hacer:

• Si la sugerencia indica que las credenciales las administra este entorno, la aplicación que inició Claude Code es la dueña de la credencial y los demás pasos de aquí no aplican: reintenta o contacta a tu administrador
• Confirma que los roles de configuración de IAM estén otorgados a la identidad con la que te autenticas
• Confirma que el modelo esté habilitado para tu proyecto. Consulta Solicitar acceso al modelo

Antes de v2.1.273, un 403 de Agent Platform mostraba en su lugar el mensaje genérico Please run /login o Failed to authenticate, que no puede renovar las credenciales de Google Cloud.

Falló la autenticación de Microsoft Foundry

Microsoft Foundry devolvió un 401 o un 403: la credencial de Azure de la solicitud fue rechazada, o la identidad detrás de ella no tiene acceso al recurso de Foundry. /login no puede generar credenciales de Azure. La sugerencia de acción en la parte central varía según tu configuración. La parte estable es el Microsoft Foundry authentication failed inicial:

Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...

Qué hacer:

• Si la sugerencia indica que las credenciales las administra este entorno, la aplicación que inició Claude Code es la dueña de la credencial y los demás pasos de aquí no aplican: reintenta o contacta a tu administrador
• Renueva la credencial que configuraste en Configurar credenciales de Azure: rota ANTHROPIC_FOUNDRY_API_KEY, genera un ANTHROPIC_FOUNDRY_AUTH_TOKEN nuevo o ejecuta az login para que la cadena de credenciales predeterminada de Microsoft Entra pueda volver a iniciar sesión
• Si la credencial está vigente, confirma que la identidad tenga acceso al recurso de Foundry. Consulta Configuración de Azure RBAC

Antes de v2.1.273, un 401 o 403 de Microsoft Foundry mostraba en su lugar el mensaje genérico Please run /login o Failed to authenticate, que no puede renovar las credenciales de Azure.

No se pudieron cargar las credenciales de AWS o Google Cloud

Claude Code no pudo obtener credenciales utilizables de la cadena de proveedores de credenciales de AWS ni de tus credenciales predeterminadas de aplicación de Google en la máquina donde se ejecuta, por lo que ninguna solicitud llegó a tu proveedor de nube. Claude Code borra sus credenciales almacenadas en caché y reintenta dos veces antes de mostrar este mensaje. El detalle después del · indica la causa específica, como una sesión de SSO vencida, credenciales predeterminadas de aplicación faltantes reportadas como Could not load the default credentials, o un inicio de sesión revocado reportado como invalid_grant:

API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.
API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

En modo no interactivo con -p y en el Agent SDK, el código de error estructurado es cloud_credential_error. Antes de v2.1.267, el mensaje mostraba solo el texto de detalle después de API Error:, y el código estructurado era server_error o unknown.

Qué hacer:

• Ejecuta el comando de inicio de sesión de tu proveedor, como aws sso login --profile myprofile o gcloud auth application-default login, y luego reintenta. Las credenciales de Bedrock, Agent Platform o Foundry no se cargan muestra cómo confirmar las credenciales fuera de Claude Code
• Si el detalle dice AWS default-chain credential resolve timed out, la cadena se colgó en lugar de fallar, así que sigue en su lugar Se agotó el tiempo de espera al resolver las credenciales de la cadena predeterminada de AWS

Se agotó el tiempo de espera al resolver las credenciales de la cadena predeterminada de AWS

La cadena de proveedores de credenciales predeterminada de AWS no produjo credenciales en 60 segundos, así que Claude Code detuvo la resolución e hizo fallar la solicitud. Este tiempo de espera es una de las causas de No se pudieron cargar las credenciales de AWS o Google Cloud. La falla está en la resolución local de credenciales: la solicitud nunca llegó a Amazon Bedrock, Claude Platform on AWS ni al endpoint de Mantle. Claude Code borra su caché de credenciales y reintenta antes de que aparezca este error, así que cuando lo ves, la cadena ya se estancó en intentos repetidos.

API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

Las causas comunes son un comando credential_process en tu perfil de AWS que espera una entrada que no puede recibir, y un contenedor o VM cuyo servicio de metadatos de instancia (IMDS) nunca responde al sondeo de la cadena.

Antes de v2.1.267, el mensaje decía API Error: AWS default-chain credential resolve timed out. Antes de v2.1.207, una cadena estancada dejaba la solicitud esperando indefinidamente en lugar de fallar.

Qué hacer:

• Ejecuta aws sts get-caller-identity en el mismo shell con el mismo AWS_PROFILE. Si también se cuelga, corrige el perfil; un comando credential_process que pide datos de forma interactiva es una causa común.
• Completa el paso de inicio de sesión antes de iniciar Claude Code, por ejemplo aws sso login --profile myprofile
• Si tu cadena ejecuta un inicio de sesión interactivo que legítimamente necesita más de 60 segundos, como SSO con MFA a través de un wrapper como aws-vault, aumenta el límite en milisegundos con CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS

Se agotó el tiempo de espera de la verificación de configuración de Bedrock esperando a AWS

Una llamada a AWS durante la verificación de credenciales del asistente de configuración de Bedrock, como la búsqueda de credenciales o la comprobación de identidad, no terminó dentro del límite de 60 segundos. El asistente deja de esperar y hace fallar el paso de verificación:

Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

El número refleja tu límite: 60 segundos de forma predeterminada, o el valor que configuraste en CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

Las causas comunes son una red o un proxy que estanca las solicitudes a AWS, incluida la renovación del token de SSO, y un asistente de credenciales que sigue esperando una entrada que no puedes ver. Aumenta el límite solo cuando el asistente legítimamente necesite más tiempo.

Una sola solicitud estancada a AWS también puede fallar por su propio tiempo de espera por solicitud, lo que muestra un mensaje más corto en el mismo paso:

A request to AWS timed out. Check your network and proxy settings, then try again.

Cuando los mismos tiempos de espera se agotan en el paso de fijación del modelo, el asistente marca un modelo como unreachable en lugar de mostrar cualquiera de los dos mensajes.

Qué hacer:

• Ejecuta aws sts get-caller-identity en el mismo shell. Si también se cuelga, el estancamiento está fuera de Claude Code, en tu red, tu proxy o el asistente de credenciales de tu perfil de AWS; corrige eso primero.
• Completa cualquier inicio de sesión interactivo antes de abrir el asistente, por ejemplo aws sso login --profile myprofile
• Si un asistente de credenciales de tu perfil de AWS legítimamente necesita más de 60 segundos para pedirte datos, aumenta el límite en milisegundos con CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS

La sesión del gateway en la nube venció

Iniciaste sesión a través de un gateway de aplicaciones de Claude, y la sesión del gateway guardada en esta máquina venció y no se pudo renovar, o el gateway ya no la acepta, por ejemplo después de que se reemplaza el secreto JWT del gateway. Si ves esta línea al iniciar claude de forma interactiva, la sesión se abrió sin haber iniciado sesión en el gateway:

Cloud gateway session expired — run /login to reconnect.

La misma línea puede aparecer a mitad de la sesión cuando la credencial del gateway vence y Claude Code no puede renovarla.

En una ejecución no interactiva, una sesión en segundo plano u otra sesión desatendida, o un subcomando de claude distinto de claude auth, Claude Code termina con este mensaje en su lugar cuando el gateway ya no acepta la sesión:

Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

Qué hacer:

• Ejecuta /login en la sesión y completa el inicio de sesión en el navegador
• Para un inicio no interactivo, inicia claude en el mismo entorno, ejecuta /login y luego vuelve a ejecutar tu comando

Se agotó el tiempo de inicio de sesión mientras esperaba que continuaras

Durante un inicio de sesión en un gateway de aplicaciones de Claude, el gateway indicó la cuenta que inició sesión y Claude Code te pidió confirmarla antes de guardar la credencial. Dejaste la confirmación abierta más allá del propio vencimiento del inicio de sesión, y el gateway no emitió ningún token de actualización que pudiera renovarla, así que Claude Code no guardó nada cuando continuaste:

Sign-in timed out while waiting for you to continue. Try again.

Qué hacer:

• Ejecuta /login de nuevo y confirma la cuenta antes de que venza el inicio de sesión

El gateway rechazó la solicitud

Iniciaste sesión a través de un gateway de aplicaciones de Claude, y una solicitud devolvió un 403: el gateway, o el servicio upstream detrás de él, la rechazó. Volver a iniciar sesión no cambia un rechazo, así que el mensaje te remite a tu administrador del gateway:

Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...

Qué hacer:

• Pide a tu administrador del gateway que busque la solicitud. La parte final API Error: contiene el rechazo que devolvió el gateway
• Para administradores: una regla de control de acceso en el gateway devuelve un 403 que el registro de auditoría guarda junto con su motivo, y la denegación de autorización de un servicio upstream se transmite según Mensajes de error de upstream

Antes de v2.1.273, un 403 en una sesión del gateway mostraba en su lugar el mensaje genérico Please run /login o Failed to authenticate, y volver a iniciar sesión no eliminaba el rechazo.

Errores de red y conexión

La mayoría de estos errores significan que una solicitud de red desde Claude Code no llegó a su destino, o algo entre Claude Code y la API alteró la respuesta en el camino de regreso; cuando una entrada también tiene una causa local, como una escritura de archivo fallida, su cuerpo lo indica. Generalmente se originan en su red local, proxy o firewall, o en la política de red del entorno en la nube.

No se puede conectar a la API

La conexión TCP a la API falló o nunca se completó. Para los códigos de error de conexión comunes, el nombre del mensaje indica el tipo de fallo y mantiene el código entre paréntesis:

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

Un código que Claude Code no reconoce aparece como Unable to connect to API seguido del código entre paréntesis. Algunos de estos mensajes pueden mostrar más de un código: Connection refused puede mostrar ConnectionRefused o ECONNREFUSED, por ejemplo, y Can't reach the API server puede mostrar ENOTFOUND o FailedToOpenSocket.

Antes de v2.1.227, cada uno de estos mensajes codificados leía Unable to connect to API seguido del código, por ejemplo Unable to connect to API (ECONNREFUSED).

Las causas comunes incluyen no tener acceso a internet, una VPN que bloquea api.anthropic.com, o un proxy corporativo requerido que no está configurado.

Qué hacer:

• Confirme que puede alcanzar el host de la API desde el mismo shell ejecutando curl -I https://api.anthropic.com. En Windows PowerShell use curl.exe -I https://api.anthropic.com para que no se use el alias Invoke-WebRequest integrado.
• Si está detrás de un proxy corporativo, establezca HTTPS_PROXY antes de lanzar Claude Code y consulte Configuración de red
• Si enruta a través de una puerta de enlace LLM o relé, establezca ANTHROPIC_BASE_URL en su dirección. Consulte Conectar Claude Code a una puerta de enlace LLM para la configuración.
• Asegúrese de que su firewall permite los hosts enumerados en Requisitos de acceso a la red
• Los fallos intermitentes se reintentan automáticamente; los fallos persistentes apuntan a un problema de red local

Si curl tiene éxito pero Claude Code aún falla, la causa suele ser algo entre el tiempo de ejecución y la red en lugar de la red misma:

• Verifique si ANTHROPIC_BASE_URL está establecido ejecutando echo $ANTHROPIC_BASE_URL, o echo $env:ANTHROPIC_BASE_URL en PowerShell, y búsquelo en el bloque env de sus archivos de configuración. Cuando está establecido, Claude Code envía solicitudes de modelo a esa dirección en lugar de api.anthropic.com, por lo que un valor residual que apunta a un proxy local o puerta de enlace que ya no se ejecuta produce Connection refused aunque curl alcance la API. Elimínelo de su perfil de shell o configuración e inicie Claude Code desde una nueva terminal.
• En Linux y WSL, verifique /etc/resolv.conf para un servidor de nombres inaccesible. WSL en particular puede heredar un resolutor roto del host.
• En macOS, un cliente VPN que fue desconectado o desinstalado puede dejar una interfaz de túnel o una regla de enrutamiento. Verifique ifconfig para interfaces utun obsoletas y elimine la extensión de red de la VPN en Configuración del Sistema.
• Docker Desktop y tiempos de ejecución de contenedores similares pueden interceptar el tráfico saliente. Ciérrelos y reintente para descartar esto.

No se puede conectar a los servicios de Anthropic

Durante la configuración de primera ejecución, Claude Code verifica que pueda alcanzar api.anthropic.com y platform.claude.com antes de mostrar el paso de inicio de sesión. Cuando alguna verificación falla, Claude Code imprime la razón y sale.

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ECONNREFUSED
Connection to api.anthropic.com timed out after 10 seconds
A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

Claude Code envía la verificación a través de la misma configuración de proxy que las solicitudes de API y da a cada sonda 10 segundos. Cuando la sonda fallida pasó a través de un proxy, el mensaje nombra la variable de entorno que lo configuró, como HTTPS_PROXY. Antes de v2.1.222, la verificación usaba un transporte de proxy diferente sin tiempo de espera: detrás de una URL de proxy con el esquema https://, podría estancarse en Checking connectivity... indefinidamente y luego fallar aunque las solicitudes de API a través del mismo proxy tengan éxito.

Claude Code omite esta verificación cuando un archivo de configuración administrado, política MDM o asistente de política establece forceLoginMethod en "gateway", o establece forceLoginGatewayUrl sin forceLoginMethod. Con cualquiera de estas configuraciones, Claude Code abre el paso de inicio de sesión en la pantalla Cloud gateway en lugar de un método de inicio de sesión de Anthropic. Claude Code también omite la verificación cuando existe una fuente de configuración administrada en la máquina pero no se puede leer, ya que esa fuente puede contener la configuración de la puerta de enlace. Antes de v2.1.247, Claude Code ejecutaba la verificación bajo esta configuración también, y salía con este error cuando los puntos finales de Anthropic eran inaccesibles.

Qué hacer:

• Si el mensaje nombra una variable de proxy, verifique que su valor apunte al proxy correcto y pida a su equipo de red que permita conexiones HTTPS a través de él al host en el mensaje. Consulte Configuración de red.
• Trabaje a través de las verificaciones en No se puede conectar a la API. La prueba curl y la orientación de firewall allí se aplican a esta verificación también.
• Si su red está abierta y el fallo persiste, Claude Code puede no estar disponible en su país

Socket is closed

Socket is closed significa que la conexión que transportaba una respuesta de transmisión se cerró mientras la respuesta aún llegaba. La causa más común es un proxy corporativo en Windows que elimina un túnel establecido a mitad de la respuesta.

Dependiendo de cuán lejos haya progresado la respuesta, Claude Code reintenta la solicitud, mantiene lo que Claude produjo, o termina el turno. Consulte Reintentos automáticos.

Antes de v2.1.214, Claude Code no reintentaba este fallo, y el turno se detenía con un error que contenía Socket is closed.

Qué hacer:

• Si ve este error, actualice a v2.1.214 o posterior con claude update, luego envíe su mensaje nuevamente
• Si los turnos siguen fallando detrás del mismo proxy después de actualizar, trabaje a través de No se puede conectar a la API y verifique la configuración del proxy en Configuración de red

La API devolvió una respuesta vacía o malformada

Claude Code muestra este error cuando su reintento sin transmisión de una solicitud de transmisión fallida obtiene un estado de éxito HTTP pero el cuerpo no es un mensaje de API de Claude: comúnmente una página de error HTML o de inicio de sesión, un cuerpo vacío, o JSON en otro formato. Un proxy, puerta de enlace o página de inicio de sesión de red respondiendo en lugar de la API es la fuente habitual. Claude Code no reintenta la solicitud, y el turno termina con este error.

API returned an empty or malformed response (HTTP 200) — check for a proxy or gateway intercepting the request.

Después de esa apertura, el mensaje informa lo que regresó y qué solicitud falló:

• Una cláusula Response: con el tipo de contenido, el tipo de cuerpo, como body is an HTML page o empty body, su tamaño en bytes, y si la respuesta llevaba un id de solicitud de Anthropic. Cuando la respuesta nombra un servidor reconocible, como nginx o cloudflare, o lleva encabezados intermediarios, como cf-ray o via, la cláusula también los enumera.
• Una oración que nombra el id de la solicitud de transmisión fallida y el fallo que desencadenó el reintento. Cuando una transmisión se había abierto antes del fallo, también informa cuántos eventos de transmisión llegaron y, si alguno lo hizo, cuánto tiempo la transmisión había estado en silencio cuando se realizó el intento.

Antes de v2.1.234, el mensaje terminaba después de intercepting the request.

Antes de v2.1.271, una respuesta que llevaba un mensaje de API válido bajo un tipo de contenido que no es JSON como text/plain también terminaba el turno con este error. Algunas puertas de enlace LLM usan ese tipo de contenido para la respuesta sin transmisión.

Qué hacer:

• Lea la cláusula Response: para ver qué sistema respondió. Un cuerpo HTML, sin id de solicitud de Anthropic, o un servidor nombrado como nginx o cloudflare significa que algo entre Claude Code y la API respondió en su lugar
• Si enruta a través de una puerta de enlace LLM, pruebe la ruta con una solicitud directa y corrija el salto que devuelve la respuesta que no es de API
• En una red con una página de inicio de sesión, como Wi-Fi de invitados, complete el inicio de sesión en un navegador, luego reintente
• Si solo la ruta sin transmisión a través de su puerta de enlace está rota, establezca CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 para desactivar este respaldo, excepto cuando el punto final de transmisión en sí devuelve 404, donde Claude Code aún recurre al respaldo

La respuesta de transmisión terminó antes de que se recibiera algún dato completo

Una respuesta de transmisión de su proveedor de modelo se completó sin entregar ningún dato utilizable, por lo que Claude Code reenviló la solicitud sin transmisión para terminar el turno. Claude Code muestra la advertencia una vez por sesión, solo en sesiones interactivas. Antes de v2.1.239, Claude Code reintentaba silenciosamente sin transmisión.

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

Claude Code envía cada solicitud afectada dos veces: el intento de transmisión vacío y el reintento. La causa habitual es un proxy o puerta de enlace que consume o transforma el cuerpo de la respuesta de transmisión en el camino de regreso.

Qué hacer:

• Configure cualquier proxy o puerta de enlace entre Claude Code y su proveedor de modelo para pasar los cuerpos de respuesta de transmisión y sus encabezados sin modificar
• En Amazon Bedrock, consulte Errores de transmisión detrás de una puerta de enlace o proxy para los requisitos de encabezado y cuerpo

La respuesta de transmisión de Bedrock tiene un content-type inesperado

Una puerta de enlace o proxy entre Claude Code y Amazon Bedrock está transformando el cuerpo de la respuesta de transmisión o su encabezado Content-Type. Amazon Bedrock transmite respuestas como application/vnd.amazon.eventstream. En lugar de decodificar un cuerpo que no puede leer, Claude Code rechaza una respuesta de transmisión exitosa que informa un content-type diferente. Claude Code no reintenta la solicitud.

Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.

Antes de v2.1.208, la misma configuración incorrecta se presentaba como API Error: Truncated event message received después de que todo el cuerpo había sido almacenado en búfer.

Qué hacer:

• Configure la puerta de enlace para pasar el cuerpo de respuesta InvokeModelWithResponseStream y su encabezado Content-Type sin modificar. Un intermediario que reemite la transmisión como eventos enviados por el servidor es una causa común.
• Establecer CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 oculta este error, pero Claude Code no decodifica un cuerpo binario bajo un encabezado reescrito, por lo que esas solicitudes recurren a una ruta más lenta sin transmisión. Consulte Errores de transmisión detrás de una puerta de enlace o proxy.

Errores de certificado SSL

Un proxy o dispositivo de seguridad en su red está interceptando el tráfico TLS con su propio certificado, y Claude Code no lo confía.

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

Antes de v2.1.273, ambos mensajes terminaban en Check your proxy or corporate SSL certificates, sin el código OpenSSL o la sugerencia NODE_EXTRA_CA_CERTS.

A partir de v2.1.199, un fallo de validación de certificado no se reintenta, por lo que este error aparece en el primer intento en lugar de después del presupuesto de reintento completo. Las versiones anteriores pasaban unos minutos reintentando antes de mostrarlo. Las condiciones TLS transitorias, como un tiempo de espera de protocolo de enlace, aún se reintentan.

Durante /login y la verificación de conectividad de inicio, el mismo fallo produce un mensaje diferente:

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

En Amazon Bedrock, las solicitudes que Claude Code envía a AWS, como las llamadas de credencial de rol STS y SSO, descubrimiento de modelo, y las verificaciones del asistente de configuración, dependen de la misma configuración de certificado. Consulte Errores de certificado detrás de un proxy que inspecciona TLS.

Qué hacer:

• Exporte el paquete de CA de su organización y apunte Claude Code a él con NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem
• Consulte Configuración de red para obtener instrucciones de configuración completas
• No establezca NODE_TLS_REJECT_UNAUTHORIZED=0, que desactiva completamente la validación de certificados

Host no permitido en una sesión en la nube

Una solicitud HTTP saliente desde una sesión en la nube o rutina fue bloqueada por la política de red del entorno.

HTTP 403
x-deny-reason: host_not_allowed

También puede ver un certificado TLS que no coincide con el certificado real del destino. Las sesiones en la nube enrutan el tráfico saliente a través de un proxy que aplica la política de red, por lo que un certificado que no coincide significa que el proxy terminó la conexión, no el destino.

Este no es un problema de red del lado del cliente. Las sesiones en la nube y rutinas se ejecutan dentro de una VM aislada cuyo tráfico saliente a través de la red de la sesión se filtra a la lista de permitidos del entorno en la nube; las operaciones de GitHub y el tráfico del conector MCP usan canales separados, por lo que pueden seguir funcionando mientras otros hosts están bloqueados. El entorno Default usa acceso Trusted, que permite la lista de permitidos predeterminada de registros de paquetes, API de proveedores en la nube, registros de contenedores, y dominios de desarrollo comunes y bloquea otros dominios en esa ruta.

Qué hacer:

Estos pasos cambian uno de sus propios entornos. Un entorno compartido por la organización se abre como solo lectura en el selector, así que pida a un Propietario que cambie su acceso de red desde la página Cloud environments en configuración de administración.

• Abra su entorno para editar, ya sea desde el formulario de la rutina o desde el selector de entorno donde inicia sesiones en la nube.
• En el diálogo Edit cloud environment, cambie Network access de Trusted a Custom, luego agregue el dominio bloqueado a Allowed domains. Ingrese un dominio por línea. Marque Also include default list of common package managers para mantener la lista de permitidos predeterminada junto con sus dominios personalizados. Seleccione Full en su lugar si desea acceso sin restricciones.
• Haga clic en Save changes. La siguiente ejecución usa la lista de permitidos actualizada. Para una sesión en la nube que ya está abierta, consulte cuándo un cambio de acceso de red llega a sesiones existentes.

Consulte Network access para niveles de acceso y la lista de permitidos predeterminada. Las sesiones de CLI locales no se ven afectadas por esta política.

El proxy rechazó la conexión

Ve este mensaje cuando Claude lee un artefacto a través del proxy que estableció en HTTPS_PROXY o una variable de proxy relacionada. El contenido del artefacto proviene de *.frame.claudeusercontent.com, por lo que Claude Code primero envía al proxy una solicitud CONNECT pidiéndole que abra un túnel a ese host. Cuando el proxy rechaza, nada llega al host, y el mensaje lleva el estado HTTP del proxy:

artifact content fetch failed (proxy refused the connection: HTTP 407)
artifact content fetch failed (proxy refused the connection: HTTP 403)
the proxy refused the connection to the artifact's content host (HTTP 502)

El estado es la respuesta del proxy a CONNECT. El host nunca respondió, por lo que cada estado apunta a una corrección diferente:

• HTTP 407: el proxy requiere credenciales que no obtuvo. Póngalas en la URL del proxy, como muestra Autenticación básica.
• HTTP 403: el proxy rechaza hacer un túnel a *.frame.claudeusercontent.com. Pida a quien ejecute el proxy que permita ese host, que Requisitos de acceso a la red enumera.
• Cualquier otro estado, como HTTP 502: el proxy no abrió el túnel por su propia razón, como no poder alcanzar el host. Busque el estado en los registros del proxy.
• unreadable reply en lugar de un estado: lo que está en la dirección del proxy no respondió con una línea de estado HTTP. Verifique que la dirección sea un proxy HTTP.

Qué hacer:

• Verifique la dirección y las credenciales en la variable de proxy, como describe Proxy configuration, luego ejecute curl -x http://proxy.example.com:8080 -I https://api.anthropic.com desde el shell en el que inicia Claude Code, usando su propia URL de proxy. En Windows PowerShell, ejecute curl.exe. Si esta sonda falla de la misma manera, corrija primero la configuración del proxy. Si tiene éxito, el rechazo es específico del host del artefacto.
• Si su red permite que Claude Code alcance el host del artefacto directamente, agregue .frame.claudeusercontent.com a NO_PROXY. Mantenga la entrada estrecha: una entrada más amplia .claudeusercontent.com también omite el proxy para bridge.claudeusercontent.com, que las organizaciones con lista de permitidos de IP necesitan mantener en el proxy.

Antes de v2.1.238, Claude Code informaba un túnel rechazado como un error de red genérico.

El servicio de entornos en la nube devolvió una respuesta vacía o inesperada

Claude Code solicita su lista de entornos en la nube en varios puntos, como cuando crea una sesión en la nube desde la CLI o ejecuta /remote-env. Cuando no puede leer la respuesta del servidor, muestra uno de estos mensajes:

The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

El servidor aceptó la solicitud pero respondió con un cuerpo que no es la lista de entornos: vacío, no JSON, o JSON sin la lista. Esto generalmente acompaña una interrupción del lado del servicio y se resuelve por sí solo. Dependiendo de la superficie que solicitó la lista, Claude Code puede agregar un prefijo, como couldn't list environments: en el diálogo /remote-env.

Qué hacer:

• Reintente la acción. Claude Code solicita la lista nuevamente cada vez
• Si el mensaje sigue apareciendo, verifique status.claude.com para incidentes activos

Antes de v2.1.236, Claude Code mostraba un TypeError de JavaScript sin procesar en lugar de estos mensajes.

No se pudo reconectar a su sesión de Remote Control

Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

Reanudar con claude --resume o claude --continue se reconecta a la sesión de Remote Control registrada en esa conversación. Este mensaje significa que la reconexión falló por una razón que puede ser temporal, como una interrupción de red o un error del servidor, por lo que Claude Code no puede confirmar si la sesión remota aún existe. Su sesión local sigue ejecutándose sin Remote Control.

Qué hacer:

• Ejecute /remote-control para reintentar la conexión
• Inicie una nueva sesión con claude --remote-control para crear una nueva sesión de Remote Control
• Para otros mensajes de inicio de Remote Control, consulte Solucionar problemas de Remote Control

Si el servidor informa en su lugar que la sesión anterior se ha ido, no ve este mensaje. Claude Code inicia una nueva sesión en su lugar o muestra Previous session is unavailable — run /remote-control to start a new one.

Las sesiones terminaron mientras esta máquina estaba sin conexión

Claude Code muestra este mensaje en la terminal que ejecuta claude remote-control después de que su máquina estuvo sin conexión el tiempo suficiente para que el servidor limpiara el entorno de Remote Control que su máquina estaba sirviendo. Las sesiones en ese entorno terminaron, y no puede reanudarlas. El recuento es el número de sesiones que terminaron.

2 sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.

Qué hacer:

• Cuando Claude Code enumera worktrees mantenidos bajo este mensaje, recoja cualquier trabajo no confirmado de ellos
• Ejecute claude remote-control para iniciar un entorno nuevo

No se pudo compartir la transcripción

Después de que acepta compartir su transcripción de sesión desde un mensaje de encuesta, como la encuesta de calidad de sesión, Claude Code la carga a Anthropic, o guarda un archivo local en su lugar en proveedores de terceros, en sesiones de puerta de enlace de aplicaciones Claude, y cuando no hay credenciales de Anthropic disponibles. Este mensaje significa que el intercambio no se completó.

Couldn't share the transcript.

La carga debe ajustarse a un límite de 8 MiB. En una sesión larga, Claude Code progresivamente elimina partes del intercambio, la configuración del modelo de la última solicitud primero, luego la conversación estructurada y las transcripciones de subagentes, y muestra este mensaje cuando no se puede enviar ninguna versión reducida o un error de red o servidor detiene la carga. Cuando Claude Code guarda un archivo local en su lugar, el mensaje significa que no pudo escribir el archivo.

Qué hacer:

• Ejecute /feedback para enviar la transcripción con una descripción de lo que sucedió. Consulte Reportar un error si /feedback no está disponible en su entorno
• Si otras solicitudes también están fallando, verifique su conexión de red y consulte No se puede conectar a la API

No se pudo enviar comentarios

Envió un informe desde el diálogo /feedback, /bug, o /share y la carga a Anthropic falló. El diálogo mantiene su texto para que pueda reintentar.

Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.

El texto después del prefijo nombra lo que falló:

• : not signed in. Run /login, then retry.: el diálogo se carga solo cuando Claude Code encontró credenciales de Anthropic cuando se abrió, y ninguna era utilizable en el momento en que envió. Por ejemplo, cerró sesión en esta máquina mientras tanto, o su inicio de sesión ya no pudo ser actualizado.
• Un paréntesis: (server returned <status>) es el código de respuesta del servicio; (request timed out) y (couldn't reach the service) son fallos de red. Cuando Claude Code no puede nombrar una razón, el paréntesis está ausente.

En la cola de borradores de comentarios, el mismo fallo termina con The draft is still queued. Try again later. en su lugar, y el borrador permanece en la cola para otro intento.

Qué hacer:

• Para la redacción no firmada, ejecute /login y envíe nuevamente
• De lo contrario, envíe nuevamente; si otras solicitudes también están fallando, verifique su conexión de red y consulte No se puede conectar a la API
• Si sigue fallando, presente el informe en github.com/anthropics/claude-code/issues, como dice el mensaje

Antes de v2.1.281, cada envío falló con este mensaje una vez que un Stop de Remote Control o un mensaje urgente entre sesiones había llegado mientras el diálogo estaba abierto. En esas versiones, cierre el diálogo, reabralo, y envíe nuevamente.

Errores de solicitud

Estos errores se relacionan con el contenido de su solicitud. La mayoría provienen de la API después de rechazarla; algunos son producidos localmente por Claude Code antes de que se envíe ninguna solicitud.

El prompt es demasiado largo

La conversación más los archivos adjuntos exceden la ventana de contexto del modelo.

Prompt is too long

En una sesión interactiva, Claude Code muestra este error como:

Context limit reached · /compact or /clear to continue

La línea nombra solo /clear cuando DISABLE_COMPACT está configurado. Las formas más largas del error, como la forma de compactación fallida a continuación, mantienen la redacción Prompt is too long ·. En la salida -p y la transcripción, el texto permanece como Prompt is too long.

Cuando desactivó la compactación automática en su configuración de usuario, la línea también lo dice:

Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

El botón Auto-compact en /config escribe autoCompactEnabled en la configuración del usuario. La sugerencia aparece solo cuando un cambio en /config tendría efecto. Por ejemplo, no aparece cuando DISABLE_AUTO_COMPACT o DISABLE_COMPACT desactivó la compactación automática. Tampoco aparece cuando un ámbito de mayor precedencia, como la configuración del proyecto o administrada, estableció autoCompactEnabled en false. Antes de v2.1.235, la línea no llevaba ninguna sugerencia de compactación automática.

Amazon Bedrock reporta esta condición como Input is too long for requested model., que Claude Code maneja de la misma manera. Antes de v2.1.217, Claude Code no reconocía la redacción de Bedrock, por lo que la compactación automática nunca se activaba en ella y /compact fallaba con el mismo error.

Una puerta de enlace de aplicaciones Claude reporta esta condición como capability_rejected: prompt_too_long cuando una nube ascendente rechaza la solicitud en la forma de error propia del proveedor. Claude Code trata el token igual que Prompt is too long. Antes de v2.1.228, Claude Code no reconocía el token, por lo que la compactación automática no se activaba en él.

Cuando la compactación automática se ejecutó en este turno y falló en un error subyacente, como un modelo no disponible o un fallo de autenticación, el mensaje nombra ese error después de un separador:

Prompt is too long · automatic compaction failed: <the underlying error>

Resuelva el error nombrado primero; /compact falla en el mismo error hasta que lo haga. Antes de v2.1.229, una compactación automática fallida mostraba Prompt is too long sin la causa.

Cuando la compactación automática se ejecuta en este error, normalmente resume sus intercambios más antiguos y mantiene los más nuevos. Como último recurso, Claude Code resume de manera diferente:

• Cuando no puede resumir ningún intercambio completo, Claude Code mantiene su mensaje más reciente palabra por palabra y resume todo lo anterior.
• En ese caso, cuando la conversación no termina con su mensaje, Claude Code resume toda la conversación en su lugar.

Claude Code omite esta recuperación cuando el contenido que llevaría adelante no contiene respuesta del modelo y menos de aproximadamente 1.000 tokens de su propio texto, como un reintento corto enviado después de un pegado de tamaño excesivo. Ejecute /clear para comenzar de nuevo. Antes de v2.1.269, la compactación fallaba siempre que no pudiera resumir un intercambio completo, por lo que una sesión en ese estado golpeaba este error de nuevo en cada turno.

Una conversación de un solo intercambio no tiene turnos anteriores para resumir. Cuando la compactación automática se habría ejecutado en uno, Claude Code omite el intento y explica qué llena la solicitud en su lugar. Cuando la API no reporta conteos de tokens en su error, el mensaje dice:

Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.

Cuando la API reporta conteos de tokens en su error, Claude Code los compara con su propia estimación del tamaño de la conversación para determinar cuál es la mayor parte de la solicitud: el contenido propio de la conversación, o el prompt del sistema, definiciones de herramientas y contenido de adjuntos que Claude Code envía con ella. Cuando el contenido propio de la conversación es la mayor parte de la solicitud, el mensaje dice:

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).

Cuando la mayor parte de la solicitud está fuera de la conversación, el mensaje dice:

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.

Antes de v2.1.162, Claude Code intentaba la compactación de todas formas y mostraba el Prompt is too long desnudo cuando fallaba.

Qué hacer:

• Ejecute /compact para resumir turnos anteriores y liberar espacio, o /clear para comenzar de nuevo. Si /compact responde Not enough messages to compact., la conversación es un solo intercambio sin nada anterior para resumir, por lo que el espacio está ocupado por ese único mensaje y lo que Claude Code envía con cada solicitud: ejecute /clear y reenvíe con menos texto pegado o adjuntos más pequeños, o reduzca las definiciones de herramientas y archivos de memoria usando los pasos a continuación
• Ejecute /context para ver un desglose de lo que está consumiendo la ventana: prompt del sistema, herramientas, archivos de memoria y mensajes
• Desactive los servidores MCP que no está utilizando con /mcp disable <name> para eliminar sus definiciones de herramientas del contexto
• Recorte los archivos de memoria CLAUDE.md grandes, o mueva las instrucciones a reglas con ámbito de ruta que se carguen solo cuando sea relevante
• La compactación automática está activada de forma predeterminada y normalmente previene este error. Si la desactivó en /config o con DISABLE_AUTO_COMPACT, vuelva a activarla. Si la mantiene desactivada, ejecute /compact usted mismo antes de que la ventana se llene.

Consulte Explorar la ventana de contexto para una vista interactiva de cómo se llena el contexto.

El contexto excede el límite de tokens

/context muestra esta advertencia en la parte superior de su salida cuando la conversación ha crecido más allá de la ventana de contexto del modelo. Las solicitudes fallan con Prompt is too long hasta que libere espacio. Una sesión interactiva muestra ese error como la línea Context limit reached.

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

Cuando el límite que excedió es una ventana de compactación, como el límite de 200K en modelos de contexto de 1M, la advertencia dice algo diferente. Una ventana de compactación puede estar por debajo de la ventana de contexto del modelo, por lo que las solicitudes más allá de ella aún pueden tener éxito.

Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

Ambas formas nombran /clear en lugar de /compact cuando ha establecido DISABLE_COMPACT.

Qué hacer:

• En una conversación de múltiples turnos, ejecute /compact para resumir turnos anteriores y liberar espacio. Para comenzar de nuevo, ejecute /clear
• Para más formas de reducir el uso, consulte Prompt is too long

Antes de v2.1.216, /context mostraba el uso por encima del 100% sin una línea de advertencia que explicara qué significaba eso o cómo recuperarse.

Solicitud demasiado grande

El cuerpo de solicitud sin procesar excedió el límite de 32MB de la API antes de la tokenización, generalmente debido a contenido pegado grande, resultados de herramientas o adjuntos. Este límite es separado de la ventana de contexto.

Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.

Cuando la solicitud fue directamente a la API de Claude y la API en sí la rechazó, Claude Code mide la conversación y redacta el mensaje según si la recuperación puede funcionar. A través de un proxy, puerta de enlace o proveedor de nube obtiene el mensaje general. Las formas medidas:

• Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).: las imágenes o documentos empujaron la solicitud más allá del límite. Claude Code reintenta con ellos eliminados.
• Request too large for the API's 32MB request limit: los mensajes solos están más allá del límite, por lo que el mensaje dice compacting cannot make it fit y Claude Code no reintenta. En modo no interactivo, el mensaje le dice que reduzca la entrada o comience una nueva sesión en su lugar.

Antes de v2.1.212, las conversaciones con suficientes imágenes acumuladas fallaban en cada turno con Request too large (max 32MB). Double press esc to go back and try with a smaller file. Antes de v2.1.229, Claude Code mostraba el consejo de adjuntos para cada rechazo, incluso cuando la compactación no podía ayudar.

Qué hacer:

• Si el mensaje dice compacting cannot make it fit, presione Esc dos veces para retroceder más allá del turno que agregó el contenido grande, o ejecute /clear para comenzar de nuevo
• De lo contrario, ejecute /compact, que elimina imágenes y adjuntos acumulados
• Haga referencia a archivos grandes por ruta en lugar de pegar su contenido, para que Claude pueda leerlos en fragmentos
• Para imágenes, consulte Image was too large a continuación

La imagen era demasiado grande

Una imagen pegada o adjunta excede los límites de tamaño o dimensión de la API.

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

Claude Code reemplaza la imagen no procesable con un marcador de posición de texto y reintenta, por lo que los mensajes posteriores tienen éxito. En versiones anteriores a 2.1.142, una imagen pegada podría permanecer en la conversación y repetir el mismo error en cada mensaje posterior. Para recuperarse en esas versiones, presione Esc dos veces y retroceda más allá del turno donde se agregó la imagen.

Qué hacer:

• Cambie el tamaño de la imagen antes de pegarla. La API acepta imágenes de hasta 8000 píxeles en el borde más largo para una sola imagen, o 2000 píxeles cuando hay muchas imágenes en contexto.
• Tome una captura de pantalla más ajustada de la región relevante en lugar de la pantalla completa

No se pudo cambiar el tamaño de la imagen

Claude Code no pudo reducir la escala de una imagen adjunta antes de enviarla a la API.

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.
Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Re-save it as an RGB PNG or JPEG and try again.
Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Save its first frame as a PNG or JPEG and try again.
Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.

Claude Code normalmente cambia el tamaño de las imágenes grandes automáticamente. Estos errores significan que la imagen no se pudo decodificar o cambiar de tamaño para caber dentro de los límites de la API.

Qué hacer:

• Si el mensaje le pide que convierta la imagen, conviértala a PNG, JPEG, GIF o WebP y adjúntela de nuevo. Claude Code puede verificar dimensiones para estos formatos desde el encabezado del archivo, sin decodificar la imagen.
• Si el mensaje reporta un límite de dimensión o tamaño, cambie el tamaño o recomprima la imagen por debajo de ese límite antes de adjuntarla.
• Si el mensaje nombra una causa, como un JPEG CMYK, un WebP animado o un archivo posiblemente dañado, guarde la imagen en el formato que sugiere el mensaje y adjúntela de nuevo.

Errores de PDF

El PDF que adjuntó no se pudo procesar. Los mensajes se muestran aquí en su forma no interactiva; en una sesión interactiva, en su lugar le piden que presione esc dos veces e intente de nuevo.

PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
PDF is password protected. Try using a CLI tool to extract or convert the PDF.
The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

Qué hacer:

• Para PDF de gran tamaño, pida a Claude que lea un rango de páginas con la herramienta Read en lugar de adjuntar el archivo completo, o extraiga texto con una herramienta como pdftotext y haga referencia al archivo de salida por ruta
• Para PDF protegidos o inválidos, elimine la contraseña o reexporte el archivo desde su aplicación de origen, luego intente de nuevo

Cuando Claude lee un rango de páginas de un PDF con la herramienta Read, la lectura puede fallar con un mensaje diferente:

pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.

Las lecturas de rango de páginas renderizan páginas con pdftoppm. Instale poppler-utils con el comando que el mensaje proporciona, o en otras plataformas una compilación de poppler que ponga pdftoppm en su PATH. Consulte Read tool behavior para ver qué PDF se leen por rango de páginas.

No se permiten entradas adicionales

Un proxy o puerta de enlace LLM entre Claude Code y la API eliminó el encabezado de solicitud anthropic-beta, por lo que la API rechazó los campos que dependen de él.

API Error: 400 ... Extra inputs are not permitted ... context_management

Claude Code envía campos exclusivos de beta como context_management junto con un encabezado anthropic-beta que los habilita. Cuando un gateway reenvía el cuerpo pero descarta el encabezado, la API ve campos que no reconoce.

Qué hacer:

• Configure su puerta de enlace para reenviar el encabezado anthropic-beta. Consulte feature pass-through para saber qué puertas de enlace deben reenviar.
• Como alternativa, establezca CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 antes de lanzar. Disable pre-release capabilities cubre el alcance exacto.

El esquema de entrada de herramienta no es válido

Una herramienta en la solicitud declaró un input_schema que falla la validación del esquema JSON de la API, por lo que la API rechazó toda la solicitud. El número después de tools. es la posición de la herramienta que falla en la lista de herramientas de la solicitud, no un nombre que pueda buscar.

API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

La primera forma significa que el esquema no es un esquema JSON válido draft 2020-12. La segunda significa que un nombre de propiedad de nivel superior no coincide con el patrón que cita el mensaje.

Claude Code excluye herramientas MCP cuyo esquema de entrada fallaría esta validación cuando carga las herramientas de un servidor, por lo que las solicitudes normalmente nunca incluyen una.

En una implementación donde la obtención de banderas está desactivada, o en una máquina cuyas banderas nunca han llegado, Claude Code registra en el registro del servidor qué herramienta sería rechazada pero la envía de todas formas, por lo que este error aún puede ocurrir.

El error también puede ocurrir para una herramienta cuyo esquema declara un dialecto de esquema JSON distinto de draft 2020-12 en $schema. Claude Code no verifica esos esquemas contra el meta-esquema del esquema JSON, aunque la verificación del nombre de propiedad de nivel superior aún se aplica.

Antes de v2.1.216, ninguna implementación ejecutaba las verificaciones de exclusión.

Qué hacer:

• Si su versión de Claude Code es anterior a v2.1.216, ejecute claude update.
• Elimine o desactive el servidor MCP que declara el esquema inválido. El error nombra la herramienta solo por posición. En v2.1.216 o posterior, verifique el registro de cada servidor para una línea que nombre una herramienta cuyo esquema de entrada sería rechazado. Si ningún registro nombra una, desactive los servidores uno a la vez.
• Si mantiene el servidor, corrija el input_schema de la herramienta. El esquema debe ser un esquema JSON válido, y los nombres de propiedad de nivel superior deben tener entre 1 y 64 caracteres de largo y usar solo letras ASCII y dígitos, _, . y -. Consulte Tools with invalid input schemas.

tool\_use.name superior a 200 caracteres

Una llamada de herramienta en el historial de conversación lleva un nombre más largo que los 200 caracteres que la API acepta en una solicitud:

API Error: 400 ... tool_use.name: String should have at most 200 characters

Claude Code corta tal nombre a 200 caracteres cuando la respuesta llega y cuando carga una conversación guardada, por lo que la llamada falla con un error de herramienta ordinario No such tool available y la conversación continúa sin este error de API.

Qué hacer:

• Ejecute claude update, luego reanude la conversación. La versión actualizada repara el nombre demasiado largo cuando carga la transcripción, por lo que una conversación que estaba atascada funciona de nuevo.

Antes de v2.1.281, el nombre demasiado largo permanecía en el historial y la API rechazaba cada solicitud que reenviaba la conversación, incluyendo /compact y --resume, por lo que este error se repetía y la conversación estaba atascada.

Hay un problema con el modelo seleccionado

El nombre del modelo configurado no fue reconocido o su cuenta carece de acceso a él. A partir de v2.1.160, la sugerencia final, que se muestra aquí en su forma interactiva, varía según la superficie.

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

Qué hacer:

• CLI interactivo: ejecute /model para elegir entre los modelos disponibles para su cuenta.
• Modo no interactivo (-p): pase --model con un alias o ID válido, o establezca ANTHROPIC_MODEL. El texto de error muestra Run --model en esta superficie.
• Agent SDK: el texto de error omite la sugerencia porque el modelo se establece mediante programación. Establezca model en Options en TypeScript o ClaudeAgentOptions(model=...) en Python, y maneje el error estructurado model_not_found para mostrar su propio reintento o selector de modelo.
• Use un alias como sonnet u opus en lugar de un ID completamente versionado. Los alias se resuelven a un valor predeterminado mantenido para que no se vuelvan obsoletos. Consulte Model configuration.
• Si el modelo incorrecto sigue apareciendo en la CLI, un ID obsoleto está configurado en algún lugar. Verifique los lugares donde puede establecer un modelo en orden de prioridad y elimine el valor obsoleto.
• Claude Code reporta un inicio de sesión de claude.ai expirado como Login expired, no como este error. Antes de v2.1.206, un inicio de sesión expirado que ya no se podía actualizar fallaba en cada modelo con este error; ejecute /login si ve eso en una versión anterior.
• Para implementaciones de la plataforma de agentes de Google Cloud, consulte Solución de problemas de la plataforma de agentes de Google Cloud.

El modelo no es un ID de modelo reconocido

La cadena que pasó a un cambio de modelo no es una que Claude Code pueda usar como modelo, por lo que rechazó el cambio sin enviar una solicitud y la sesión mantiene su modelo actual. Puede obtener este error cuando un modelo se establece a través del método Agent SDK setModel(), por una aplicación que ejecuta la CLI de Claude Code para usted, como la aplicación de escritorio, o cuando elige un modelo desde un dispositivo conectado a través de Remote Control. Antes de v2.1.200, Claude Code guardaba la cadena y fallaba en la siguiente solicitud con There's an issue with the selected model.

Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

En este ejemplo una aplicación envió el nombre para mostrar Sonnet 5, que el mensaje repite sin su espacio. La sugerencia final nombra el alias o ID de modelo más cercano. Cuando nada es lo suficientemente cercano, dice Run /model to see available models. en su lugar. En una sesión que la aplicación de escritorio inicia para usted, la sugerencia sin coincidencia dice Switch to a different model.

Cuando cambia a través del Agent SDK o una aplicación en la API de Anthropic, solo una cadena que no puede ser un ID de modelo obtiene este error, como un nombre para mostrar o una cadena vacía.

Cuando elige un modelo desde un dispositivo Remote Control, Claude Code verifica la cadena localmente. Cualquier cadena que no sea un alias de modelo, un modelo que Claude Code enumera o que usted configuró, o un ID que comienza con claude- obtiene este error, un ID mal escrito como claud-sonnet-5 incluido. Antes de v2.1.260, esta verificación no cubría las selecciones de Remote Control, por lo que una cadena no reconocida se aplicaba y fallaba en la siguiente solicitud.

Qué hacer:

• Ejecute /model sin argumento para abrir el selector y elegir entre los modelos disponibles para su cuenta, luego pase el alias o ID que se muestra allí
• Si usó un alias que una versión más nueva de Claude Code admite, ejecute claude update, o pase el ID completo del modelo en su lugar. El servidor aún puede requerir una versión mínima de Claude Code para ese modelo; consulte Claude Code does not support this model.
• Un modelo guardado antes de v2.1.200 no se repara con esta verificación. Si un valor obsoleto sigue apareciendo, elimínelo de las ubicaciones enumeradas en Setting your model.
• En cualquier proveedor que no sea la API de Anthropic, o detrás de una puerta de enlace o ANTHROPIC_BASE_URL personalizado, solo una cadena vacía obtiene este error. Claude Code aún puede escribir la línea de diagnóstico de modelo no reconocido en el momento de la solicitud, en cada proveedor.

Modelo no encontrado

Cambió a un modelo por nombre y Claude Code no pudo confirmar que existe un modelo con ese nombre. Cuando el nombre no es un alias de modelo u otra ortografía que Claude Code acepta localmente, Claude Code lo verifica con una solicitud mínima de API, y este error es generalmente la respuesta de su punto final de API. Con /model <name>, un nombre que no puede ser un ID de modelo en absoluto, como uno que contiene espacios, obtiene el mismo mensaje.

Model 'claude-opus-9' not found

En proveedores con ID de modelo específicos del proveedor, el mensaje puede agregar una sugerencia Try '...' instead que nombra el ID de su proveedor para un modelo alternativo.

Qué hacer:

• Ejecute /model sin argumento y elija entre los modelos disponibles para su cuenta, o use un alias de modelo como sonnet, que se resuelve a un valor predeterminado mantenido
• Si escribió un ID completo, verifíquelo contra el catálogo de modelos de su proveedor. Un modelo recién lanzado puede estar disponible en la API de Anthropic antes de que su proveedor o región lo ofrezca.
• En el Agent SDK, setModel() falla con este mensaje y la sesión sigue ejecutándose en su modelo anterior. En el SDK de TypeScript, llame a supportedModels() para enumerar los modelos a los que puede cambiar.
• Antes de v2.1.265, /model también rechazaba la ortografía del alias opusplan[1m] con este error. En esas versiones, actualice Claude Code, o establezca el modelo en settings o con --model en su lugar.

No se pudo confirmar el modelo con la API

Cambió de modelos a través del método Agent SDK setModel() o una aplicación que ejecuta la CLI de Claude Code para usted, como la aplicación de escritorio, y la solicitud que confirma el ID del modelo con su punto final de API no obtuvo respuesta dentro de cinco segundos. La sesión mantiene su modelo actual.

Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.

En una sesión que la aplicación de escritorio inicia para usted, el mensaje termina en Try again.

Qué hacer:

• Cambie al modelo de nuevo
• Si el cambio sigue fallando, verifique que Claude Code pueda alcanzar su punto final de API; consulte Network and connection errors

Error de API al verificar el modelo seleccionado

Eligió un modelo con /model <name>, o una aplicación conectada a la sesión solicitó el cambio. La API rechazó la solicitud mínima que Claude Code envía para verificar el modelo, por una razón que no tiene entrada propia, como un límite de velocidad o un error del servidor. La sesión mantiene su modelo actual, y el mensaje termina diciendo así:

API error: 429 <the server's explanation> · model not changed

El medio del mensaje es el estado HTTP y la explicación propia del servidor.

Qué hacer:

• Actúe sobre la explicación del servidor; para un límite de velocidad o un estado 5xx, espere y elija el modelo de nuevo
• Los rechazos con su propia redacción están cubiertos por las entradas circundantes, como Model not found y Model is restricted by your organization's settings

Claude Opus no está disponible con el plan Claude Pro

Su plan de suscripción activo no incluye el modelo que seleccionó.

Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.

En una sesión que la aplicación de escritorio Claude inicia, el mensaje dice que sign out and sign in again en lugar de nombrar los comandos.

Qué hacer:

• Ejecute /model y seleccione un modelo que su plan incluya
• Si actualizó su plan recientemente y aún ve esto, ejecute /logout y luego /login. El token almacenado refleja su plan en el momento en que inició sesión, por lo que actualizar en claude.ai no tiene efecto en una sesión existente hasta que se reautentique.
• Consulte claude.com/pricing para ver qué modelos incluye cada plan

Claude Code no admite este modelo

La API rechazó la solicitud con un 400 porque su versión de Claude Code está por debajo de un mínimo requerido. Ya sea que el modelo que seleccionó requiera una versión más nueva, que el servidor verifica por modelo, o que la política de su organización requiera una. El 400 lleva el código de error claude_code_version_too_old, y el mensaje dice cuál es el mínimo que se aplica.

API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.

La redacción de la política organizacional dice:

API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.

La versión que la API verifica es la que reporta el binario de Claude Code que realizó la solicitud.

Qué hacer:

Actualice ese binario, luego comience una nueva sesión. De dónde vino el binario decide cómo, excepto en un entorno autohospedado:

• Para la redacción por modelo, puede seguir trabajando en la sesión actual cambiando a otro modelo: ejecute /model en la CLI, llame a setModel() en el objeto Query del SDK de TypeScript en modo de entrada de transmisión, o llame a set_model() en el ClaudeSDKClient del SDK de Python
• Para la redacción de la política organizacional, actualice antes de continuar

El modelo está restringido por la configuración de su organización

Su administrador de organización ha deshabilitado este modelo en la consola de administración de claude.ai, o está excluido por la configuración administrada a través de una lista de permitidos availableModels o una lista deniedModels. El aviso aparece al inicio cuando --model, ANTHROPIC_MODEL o la configuración model nombró el modelo restringido, y nombra el modelo que la sesión usa en su lugar. Si la configuración administrada no deja ningún modelo permitido para que la sesión use, consulte Managed settings block the default model. El aviso de sustitución también puede aparecer a mitad de sesión después de que un administrador desactive el modelo en el que se ejecuta una sesión en la consola de administración de claude.ai.

Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

Escribir /model <name> para un modelo restringido se rechaza y la sesión mantiene su modelo actual. Para un modelo deshabilitado en la consola de administración, el rechazo dice Model '<name>' is restricted by your organization's settings. Run /model to choose a different model. Para un modelo que la configuración administrada excluye, dice Model '<name>' is not available. Your organization restricts model selection.

Un aviso prefijado con un nombre de agente, habilidad o comando significa que la restricción se aplicó a ese modelo solicitado del subagente: el subagente se ejecuta en el modelo sustituido y el modelo de su sesión no cambia. Antes de v2.1.223, Claude Code mostraba el aviso solo para subagentes lanzados con la herramienta Agent.

Claude Code trata un alias de familia de modelo, uno de opus, sonnet, haiku o fable, como una solicitud de esa familia en lugar de su versión más nueva. En la API de Anthropic y en Claude Platform on AWS, un alias de familia restringido se resuelve a la versión más nueva de la familia que la configuración de su organización permite, y el aviso de sustitución nombra esa versión. Claude Code rechaza /model <alias> solo cuando cada versión de la familia está restringida. Antes de v2.1.205, un alias de familia se sustituía o rechazaba basándose solo en su versión más nueva, incluso cuando una versión anterior de la misma familia estaba permitida.

Qué hacer:

• Ejecute /model para elegir entre los modelos que su organización permite. Los modelos restringidos están ocultos en el selector.
• Si el modelo restringido se estableció en --model, ANTHROPIC_MODEL, el campo model de un archivo de configuración, o el frontmatter model de un subagente, habilidad o comando, elimine o actualice ese valor para que el aviso no se repita
• Si necesita acceso al modelo restringido, pida a su administrador de organización que lo habilite. Consulte Organization model restrictions.

No se puede cambiar al modelo predeterminado

Eligió el modelo Predeterminado, por ejemplo seleccionando la fila Predeterminada en el selector /model o escribiendo /model default. Claude Code rechazó el cambio, por lo que la sesión mantiene su modelo actual.

Can't switch to the default model: your organization's managed settings block it (claude-opus-4-6) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".

La redacción después de los dos puntos nombra lo que bloqueó el cambio:

• your organization's managed settings block it ... in "deniedModels": una lista de negación administrada bloquea el modelo al que se resuelve la opción Predeterminada
• your organization allows only the models listed in "availableModels": una lista de permitidos availableModels administrada con availableModelsMatch establecido en "exact" deja fuera el modelo al que se resuelve la opción Predeterminada
• Claude Code couldn't read your organization's managed settings to check which models they allow: la configuración administrada no se pudo leer, y Claude Code rechaza el cambio en lugar de aplicarlo sin verificar

Qué hacer:

• Para las redacciones deniedModels y availableModels, ejecute /model y elija un modelo que su organización permita por nombre
• Pida a su administrador que actualice la configuración administrada que el mensaje nombra
• Para la redacción couldn't read, reinicie Claude Code; si sigue sucediendo, pida a su administrador que verifique la configuración administrada

Si una sesión en su lugar falla al iniciarse con un mensaje Claude Code can't start bajo esta configuración administrada, consulte Managed settings block the default model.

El cambio de modelo fue bloqueado por un hook PreModelSwitch

Un hook PreModelSwitch no aprobó el cambio de modelo que usted o un cliente solicitó, por lo que la sesión mantiene su modelo actual. Cuando el cambio provino de un host Agent SDK o Remote Control en lugar de un comando que escribió, el mensaje dice Model switch blocked by a PreModelSwitch hook sin nombrar el modelo de destino.

Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.

La razón después de los dos puntos dice qué rechazó el cambio:

• Una razón que escribió un hook: un hook PreModelSwitch proporcionó esa razón cuando negó el cambio o pidió confirmación. Aborde lo que pide, o elija un modelo que sus hooks permitan.
• PreModelSwitch hook <name> did not respond before its timeout: un hook que no responde antes de su timeout bloquea el cambio. Corrija el comando colgado o aumente el timeout de ese hook, luego cambie de nuevo.
• confirmation required, and this session cannot ask: un hook respondió ask sin una razón, y una solicitud de control no tiene forma de mostrar el mensaje de confirmación. Una orden /model en una ejecución -p reporta la misma condición con (run /model interactively to confirm) después de la razón. Haga el cambio desde una sesión interactiva, o cambie la decisión del hook para este modelo.
• so organization-managed PreModelSwitch hooks could not be checked: Claude Code no pudo determinar qué hooks PreModelSwitch sus plugins administrados de la organización entregan, por ejemplo porque un plugin administrado no se cargó. Uno de esos hooks podría bloquear el cambio, por lo que Claude Code se niega en lugar de aplicar el cambio sin verificar. El inicio de la razón nombra qué falló. Claude Code vuelve a verificar en cada intento de cambio, por lo que una falla que se ha aclarado desde entonces deja de bloquear; si sigue fallando, ejecute claude --debug y cambie de nuevo para capturar los detalles, luego corrija el plugin o pida a su administrador que lo corrija.
• a PreModelSwitch hook failed before answering o PreModelSwitch hooks were cancelled (the control stream closed) before answering: la ejecución del hook terminó sin un veredicto, y Claude Code no trata eso como aprobación. Ejecute claude --debug para ver qué falló, luego cambie de nuevo.

Antes de v2.1.260, el rechazo del plugin administrado decía plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log. Claude Code reintentó la carga del plugin una vez y luego rechazó cambios posteriores en la sesión, incluso cuando su organización no administraba plugins. Reinicie la sesión para ejecutar la carga del plugin de nuevo en esas versiones.

No se pudo guardar como su valor predeterminado

Eligió un modelo para guardar como su valor predeterminado, por ejemplo con /model <name> o Enter en el selector /model, y Claude Code no pudo escribir la selección en su archivo de configuración de usuario, ~/.claude/settings.json. El cambio en sí se aplicó, por lo que la sesión actual se ejecuta en el modelo que eligió, pero su valor predeterminado no cambia y la siguiente sesión comienza con el valor anterior.

Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)

La razón después de la ruta del archivo dice qué falló:

• can't be written (<code>): la escritura falló con el código de error del sistema operativo entre paréntesis, como EROFS cuando el archivo, o el archivo al que vincula, se encuentra en un sistema de archivos que rechaza escrituras. Haga el archivo escribible y cambie de nuevo. Si otra herramienta genera el archivo, establezca la clave model en esa herramienta en su lugar; consulte A change you made in Claude Code is lost in new sessions.
• isn't valid JSON: el archivo en disco no se analiza, y Claude Code lo deja sin tocar en lugar de sobrescribir contenido que no puede leer de vuelta. Corrija el error de sintaxis, luego cambie de nuevo; consulte Fix a broken settings file.

Un aviso que termina couldn't confirm it was saved as your default (~/.claude/settings.json is still being written) significa que la escritura no había terminado después de tres segundos. Continúa en segundo plano, por lo que el valor predeterminado aún puede guardarse; verifique qué modelo comienza su siguiente sesión, o ejecute /model <name> de nuevo.

Antes de v2.1.265, el aviso decía que el modelo fue saved as your default for new sessions incluso cuando la escritura falló.

thinking.type.enabled no es compatible con este modelo

Su versión de Claude Code es anterior a la mínima para el modelo seleccionado. La CLI envió una configuración de pensamiento que el modelo ya no acepta.

API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Qué hacer:

• Ejecute claude update y reinicie Claude Code. Opus 4.7 necesita v2.1.111 o posterior. Opus 4.8 necesita v2.1.154 o posterior. Sonnet 5 necesita v2.1.197 o posterior. Opus 5 necesita v2.1.219 o posterior. Opus 5.5 necesita v2.1.280 o posterior. Sonnet 5.5 necesita v2.1.284 o posterior
• Si no puede actualizar, ejecute /model y seleccione Opus 4.6 o Sonnet 4.6 en su lugar
• Si encuentra esto en el Agent SDK, actualice el paquete SDK en su lugar. Opus 4.8 necesita TypeScript SDK v0.3.154 o posterior y Python SDK v0.2.88 o posterior. Sonnet 5 necesita TypeScript SDK v0.3.197 o posterior. Opus 5 necesita TypeScript SDK v0.3.219 o posterior. Opus 5.5 necesita TypeScript SDK v0.3.280 o posterior. Sonnet 5.5 necesita TypeScript SDK v0.3.284 o posterior

El esfuerzo no está disponible con el pensamiento desactivado

Desactivó el pensamiento extendido y ejecutó en un nivel de esfuerzo superior a high. El modelo no acepta esa combinación, por lo que la API rechazó la solicitud.

API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)

La sugerencia después de · varía según la sesión: en una sesión no interactiva dice use --effort high (or the effortLevel setting), y en una sesión que la aplicación de escritorio Claude inicia dice you can lower effort to High.

Qué hacer:

• Baje el nivel de esfuerzo a high o inferior.
• Active el pensamiento de nuevo, por ejemplo desestableciendo MAX_THINKING_TOKENS o eliminando "alwaysThinkingEnabled": false de su configuración.

Antes de v2.1.242, Claude Code mostraba el mensaje propio de la API: API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. Antes de v2.1.251, Claude Code enviaba la solicitud en el nivel de esfuerzo que estableció, por lo que Opus 5 rechazaba cada solicitud superior a high con el pensamiento desactivado. Claude Code ahora envía esfuerzo high en su lugar a modelos que sabe que rechazan la combinación, como Opus 5.

El presupuesto de pensamiento excede el límite de salida

El presupuesto de pensamiento extendido configurado excede la longitud de respuesta máxima, por lo que no hay espacio para la respuesta real.

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

Qué hacer:

• Aumente CLAUDE_CODE_MAX_OUTPUT_TOKENS por encima del presupuesto de pensamiento
• Consulte Extended thinking para cómo el presupuesto interactúa con la longitud de salida

Desajuste de bloque de uso de herramienta o pensamiento

El historial de conversación llegó a la API en un estado inconsistente.

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 orphaned tool_result in conversation history. Run /rewind to recover the conversation.
API Error: 400 duplicate tool_use ID in conversation history. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified

Todas las variantes significan lo mismo: la secuencia de bloques tool_use, tool_result y thinking en el historial ya no coincide con lo que la API espera.

Qué hacer:

• Si está usando Opus 4.7 u Opus 4.8, ejecute claude update primero. Las versiones anteriores a v2.1.156 pueden activar este error durante el uso normal de herramientas, y /rewind no lo borra.
• Ejecute /rewind, o presione Esc dos veces, para retroceder a un punto de control antes del turno corrupto y continuar desde allí. Consulte Checkpointing para cómo se crean y restauran los puntos de control.

Datos inválidos en bloque redacted\_thinking

La API rechazó la solicitud con un 400 porque no pudo aceptar un bloque redacted_thinking que un turno anterior en el historial de conversación lleva.

API Error: 400 ... Invalid `data` in `redacted_thinking` block

Claude Code deja el pensamiento anterior de la conversación fuera de la solicitud y reintenta una vez, por lo que la sesión continúa sin mostrar el error. Antes de v2.1.282, Claude Code mantenía el bloque rechazado, y cada turno posterior fallaba con el mismo error.

Qué hacer:

• Si está en v2.1.281 o anterior y cada turno falla con este error, ejecute claude update y reanude la sesión
• Si el error persiste, ejecute /clear para comenzar una conversación que no lleve el bloque

Contenido de herramienta no compatible eliminado

Cuando Claude Code se conecta directamente a la API de Anthropic y carga o obtiene una vista previa de una sesión guardada, elimina el contenido de herramienta que la API de Anthropic no acepta y deja esta línea donde se encontraba contenido eliminado entre dos bloques de pensamiento:

[Unsupported tool content removed]

Tal contenido llega a un archivo de sesión cuando algo que no es la API de Anthropic responde en el formato de la API, típicamente un proxy de terceros establecido a través de ANTHROPIC_BASE_URL que traduce llamadas de herramientas de otro proveedor. Claude Code lo elimina solo cuando la sesión se conecta directamente a la API de Anthropic, y carga el historial guardado tal como es cuando la sesión se ejecuta a través de un proxy o en otro proveedor. Antes de v2.1.246, Claude Code enviaba el uso de herramienta y su resultado de vuelta a la API, y cada turno de la sesión reanudada fallaba con un error 400 como messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ....

Qué hacer:

• Ninguno necesario cuando ve la línea de marcador de posición. La sesión continúa sin el contenido eliminado.
• Si cada turno de una sesión reanudada falla con el error 400 en su lugar, ejecute claude update y reanude la sesión de nuevo. Las versiones anteriores a v2.1.246 no eliminan el contenido.

role 'system' debe preceder a un mensaje 'assistant'

La API rechazó la solicitud con un 400 porque un mensaje del sistema se encuentra en una posición en la conversación que no acepta:

API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...

Claude Code envía parte de su texto de recordatorio y adjuntos como mensajes del sistema dentro de la conversación. Cuando la API rechaza la posición de uno, Claude Code reintenta la solicitud una vez con ese texto enviado como mensajes de usuario ordinarios en su lugar. Las redacciones hermanas de la API, como use the top-level 'system' parameter for the initial system prompt, obtienen la misma recuperación.

Cuando el error aparece, el mensaje del sistema rechazado no es uno que Claude Code pueda eliminar. Eso generalmente significa que un proxy o puerta de enlace LLM entre Claude Code y la API agregó un mensaje del sistema propio.

Qué hacer:

• Si el error se repite en cada turno detrás de un proxy o puerta de enlace configurada a través de ANTHROPIC_BASE_URL, conéctese sin el proxy para confirmar la fuente, e informe el error a quien lo opera
• Ejecute /clear para comenzar una conversación nueva. Si el error regresa allí también, la causa está en la ruta de solicitud, no en la conversación guardada.

Antes de v2.1.280, Claude Code no reconocía esta redacción, por lo que el error también aparecía cuando el mensaje del sistema rechazado era uno que Claude Code en sí envió, y cada turno posterior de la conversación fallaba de la misma manera.

Contenido\_encriptado inválido en bloque search\_result

La API rechazó la solicitud con un 400 porque el historial de conversación contiene contenido de búsqueda web alojado que no puede descifrar. La redacción nombra el campo que no puede leer:

API Error: 400 ... Invalid `encrypted_content` in `search_result` block
API Error: 400 ... Invalid `encrypted_index` in `text` block
API Error: 400 ... Failed to decrypt web search result content
API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block

Los resultados de la herramienta de búsqueda web alojada de la API llevan campos encriptados que solo la API puede leer. El encrypted_stdout nombra la salida de un programa de ejecución de código alojado que leyó tales resultados, que la API también encripta. La API rechaza una solicitud que reproduce contenido que no puede descifrar, como contenido producido para una organización diferente.

La propia herramienta WebSearch de Claude Code registra los resultados de búsqueda como texto sin formato, por lo que estos bloques generalmente llegan a una conversación a través de un proxy o puerta de enlace LLM que ejecutó búsqueda web alojada en sí.

Para las tres redacciones de búsqueda web, Claude Code deja las llamadas de búsqueda, resultados y citas fuera de lo que envía y reintenta la solicitud una vez, por lo que la sesión continúa sin mostrar el error. La redacción encrypted_stdout no tiene tal recuperación, por lo que ese mensaje aún le llega. Antes de v2.1.282, Claude Code mantenía los bloques de búsqueda web rechazados también, y cada turno posterior y /compact fallaban de la misma manera.

Qué hacer:

• Si está en v2.1.281 o anterior y cada turno falla con una de las redacciones de búsqueda web, ejecute claude update y reanude la sesión
• Si el error persiste, o el mensaje nombra encrypted_stdout, ejecute /rewind para retroceder a un punto de control antes del turno que agregó el contenido, o ejecute /clear para comenzar una conversación que no lo lleve
• Si ejecuta Claude Code detrás de un proxy o puerta de enlace, informe el error a quien lo opera

Rechazo de política de uso

La API se negó a responder porque el contenido en la conversación activó una verificación de Política de uso.

El mensaje incluye un ID de solicitud y un ID de mensaje que puede citar al soporte si cree que el rechazo es incorrecto.

API Error: Opus 4.6 can't help with this. Start a new session to continue.

Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

El mensaje nombra el modelo que rechazó, o Claude cuando no se registra ningún modelo.

La verificación evalúa la conversación completa, no solo su mensaje más reciente, por lo que enviar un nuevo mensaje en la misma sesión generalmente reactiva el mismo rechazo. Lo mismo se aplica después de salir y reabrir la sesión con --continue o --resume, ya que la transcripción en disco aún contiene el contenido que activa. En Amazon Bedrock, Plataforma de agentes de Google Cloud y Microsoft Foundry, este mensaje también cubre solicitudes que las medidas de seguridad del modelo marcaron como un tema de ciberseguridad. Consulte Safety measures flagged a cybersecurity topic.

Antes de v2.1.219, el mensaje decía Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

Qué hacer:

• Presione Esc dos veces o ejecute /rewind para retroceder a un punto de control antes del turno que activó el rechazo, luego reformule o tome un enfoque diferente. Consulte Checkpointing.
• Si no puede identificar qué turno lo causó, ejecute /clear para comenzar una conversación nueva en el mismo proyecto. Su conversación anterior se conserva en disco y permanece disponible en /resume.
• En modo no interactivo (-p), donde el retroceso no está disponible, reintente con un mensaje reformulado en una nueva sesión sin --continue. Las verificaciones de política varían según el modelo, por lo que cambiar a un modelo diferente con --model también puede resolver el rechazo en algunos casos.

Las medidas de seguridad marcaron un tema de ciberseguridad

Las medidas de seguridad del modelo marcaron el contenido en la conversación como un tema de ciberseguridad. El mensaje nombra el modelo que marcó la solicitud:

API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

El mensaje vincula al Programa de verificación de ciberseguridad, que otorga acceso para trabajo de ciberseguridad legítimo. En Opus 5.5 y Sonnet 5.5, el mensaje abre con <model>'s safeguards flagged this session en su lugar. Cuando la categoría marcada tiene un modelo alternativo disponible, Claude Code cambia de modelos en lugar de mostrar este error.

En Amazon Bedrock, Plataforma de agentes de Google Cloud y Microsoft Foundry, una bandera de ciberseguridad produce el mensaje de rechazo de política de uso en su lugar.

La protección en sí es del lado del servidor y es anterior a v2.1.203; los lanzamientos de cliente desde entonces han cambiado solo la redacción del mensaje. De v2.1.203 a v2.1.218, el mensaje decía <model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: seguido del mismo enlace del centro de ayuda, y las sesiones interactivas agregaban If you were not engaging in a cybersecurity topic, please send feedback via /feedback. Antes de v2.1.203, decía <model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption: seguido de un enlace de formulario de exención.

Qué hacer:

• Si su trabajo requiere este contenido, solicite acceso a través del Programa de verificación de ciberseguridad
• Si su solicitud no era sobre un tema de ciberseguridad, ejecute /feedback para reportar el falso positivo
• Para seguir trabajando en la misma sesión, presione Esc dos veces o ejecute /rewind para retroceder a un punto de control antes del turno que activó la bandera, luego tome un enfoque diferente. Consulte Checkpointing.

Errores de instalación

Estos errores aparecen durante la instalación o actualización de Claude Code, desde el script de instalación, claude install, o claude update. Para problemas de command not found, PATH, permisos y TLS durante la configuración, consulte Solucionar problemas de instalación e inicio de sesión.

La instalación fue interrumpida antes de poder finalizar

El script de instalación informa cuando el paso claude install es terminado por una señal. En Linux, el código de salida 137 significa que el proceso recibió SIGKILL, y en un host con poca memoria, generalmente es el asesino de falta de memoria (OOM) del kernel. El script imprime esta explicación y sale con el código 137:

Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

Para cualquier otra señal fatal, y para el código de salida 137 en macOS, el script imprime Installation was killed before it could finish (exit code <N>) con el código de salida real y omite la explicación de falta de memoria. El mensaje proviene del script de instalación que usan macOS y Linux, que también cubre instalaciones dentro de WSL; los scripts de instalación nativos de Windows nunca lo imprimen. Antes de v2.1.200, el script salía solo con la línea Killed desnuda del shell.

Qué hacer:

• Detenga otros procesos para liberar memoria, luego vuelva a ejecutar el instalador
• Agregue espacio de intercambio o muévase a una instancia más grande. Consulte Instalación interrumpida en servidores Linux con poca memoria para los comandos del archivo de intercambio.

La conexión se interrumpió mientras se descargaba la actualización

La conexión al servidor de descarga se cerró mientras claude install o claude update estaba obteniendo el binario de Claude Code, y los reintentos no se recuperaron. Claude Code reintenta la descarga cuando la conexión se interrumpe, la transferencia se estanca o el archivo descargado falla su suma de verificación, hasta tres intentos en total. Un error HTTP completado, como un 404, no se reintenta porque el servidor ya respondió. Antes de v2.1.202, una única conexión interrumpida fallaba la descarga inmediatamente con el error desnudo aborted en lugar de reintentar.

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

El texto entre paréntesis nombra qué intento falló y el error de red subyacente. claude update precede el mensaje con Error: Failed to install native update en stderr.

Una descarga que permanece conectada pero no se completa dentro de 10 minutos falla con Download timed out: exceeded the total deadline en su lugar. Claude Code no reintenta una descarga agotada, porque una conexión demasiado lenta para terminar dentro del plazo no terminará en un reintento inmediato. Los pasos a continuación se aplican a ambos mensajes.

Un proxy o puerta de enlace puede cerrar una transferencia larga antes de que finalice, y el binario de Claude Code es una descarga grande.

Qué hacer:

• Ejecute claude update nuevamente. En una red por lo demás saludable, la descarga generalmente tiene éxito en la siguiente ejecución. Para el mensaje de tiempo agotado, ejecútelo nuevamente desde una red más rápida o menos limitada.
• Si su red requiere un proxy, establezca HTTPS_PROXY antes de ejecutar el instalador o claude update. Consulte Verificar conectividad de red.
• Si un proxy corporativo sigue cerrando la transferencia, pida a su equipo de red que permita la descarga completa desde downloads.claude.ai. Consulte Requisitos de acceso a la red.
• Ejecute claude doctor desde su shell para diagnósticos de instalación

Errores de la línea de comandos

Estos errores provienen de la línea de comandos claude y sus subcomandos, de un nombre de comando que envías en el prompt y de comandos como /security-review que recopilan contexto ejecutando comandos de shell antes de que se ejecute su prompt. También provienen de /tui, que vuelve a iniciar la CLI.

Conflicto entre `--bg` y `--print`

Este mensaje requiere Claude Code v2.1.198 o posterior. Combinaste --bg con -p o --print en la misma invocación de claude. --bg inicia una sesión en segundo plano a la que luego te conectas con claude agents, mientras que --print se ejecuta de forma no interactiva y nunca inicia la sesión interactiva a la que se conecta claude agents. Antes de v2.1.198, esta combinación creaba silenciosamente una tarea en segundo plano a la que nunca era posible conectarse.

--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

Qué hacer:

• Quita -p o --print. --bg recibe el prompt como su argumento posicional, así que claude --bg "<task>" es el comando completo. Consulta Dispatch new agents from your shell.
• Para ejecutar el prompt de forma no interactiva e imprimir el resultado en lugar de crear una sesión en segundo plano, quita --bg y ejecuta claude -p "<task>"

Conflicto entre un flag de prompt del sistema y su forma de archivo

Pasaste --append-subagent-system-prompt junto con --append-subagent-system-prompt-file en una misma invocación de claude, así que claude termina con código 1 en lugar de iniciar la sesión:

Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.

Antes de v2.1.283, claude terminaba de la misma manera cuando pasabas --system-prompt con --system-prompt-file, o --append-system-prompt con --append-system-prompt-file, porque esos pares entraban en conflicto en lugar de combinarse. En esas versiones, el mensaje nombra el par que combinaste.

Qué hacer:

• Conserva una forma del flag y quita la otra. Para combinar un archivo de prompt fijo con texto específico de cada ejecución, fusiona el texto en el archivo antes de iniciar en lugar de pasar ambos flags

Configuración de `--agents` no válida

El valor que pasaste a --agents no es válido, así que claude termina con código 1 en lugar de iniciar la sesión. Cuando pasas --safe-mode o estableces CLAUDE_CODE_SAFE_MODE, Claude Code ignora --agents por completo. Con --resume o --continue, un valor JSON en línea no se verifica y la sesión se inicia; un valor leído desde un archivo se verifica en cada inicio. Antes de v2.1.242, Claude Code iniciaba la sesión de todos modos.

Error: Invalid --agents configuration:
<what failed>

Lo que sigue a la primera línea depende de cómo falló el valor. Claude Code ejecuta estas comprobaciones en orden y se detiene en la primera que falla. Si tu valor tiene dos tipos de problema, ves el segundo solo después de corregir el primero:

1. Cuando el valor comienza con { pero no se puede analizar como JSON, o el contenido de un archivo de --agents no se puede analizar, Claude Code imprime una línea invalid JSON: con el mensaje propio del analizador de JSON
2. Cuando se analiza correctamente pero una definición de agente no coincide con el esquema de los subagentes definidos por CLI, Claude Code imprime una línea por problema
3. Cuando el nombre de un agente comienza con -, Claude Code imprime <name>: agent names must not start with '-'

Cuando hay más de 20 líneas de problemas, Claude Code imprime las primeras 20 y reemplaza el resto con …and N more.

Con --print, --agents también acepta la ruta a un archivo JSON en lugar del objeto en línea. Antes de v2.1.281, --agents aceptaba solo JSON en línea y trataba una ruta de archivo como JSON no válido. La forma de archivo tiene sus propios rechazos, que se imprimen en lugar de este mensaje, entre ellos:

• Error: --agents takes a JSON object, or a file path only with --print (-p): Claude Code leyó el valor como una ruta de archivo en una sesión interactiva. Pasa las definiciones como JSON en línea, o agrega -p para leerlas desde un archivo.
• Error: --agents file not found: <path>: no existe ningún archivo en esa ruta. Un valor que no comienza con { y no es JSON válido se lee como ruta, así que un JSON en línea que tu shell haya alterado también puede fallar de esta forma. Revisa la ruta o las comillas y vuelve a ejecutar el comando.

Qué hacer:

• Corrige cada problema que enumera el mensaje y vuelve a ejecutar el comando. Consulta los campos que acepta un subagente definido por CLI.

No se pueden crear sesiones en la nube desde una sesión `--restricted`

Cuando inicias una sesión con --restricted, Claude Code se niega a crear sesiones en la nube desde ella, porque la nueva sesión se ejecutaría fuera del proceso restringido y no aplicaría el modo restringido. Claude Code lo rechaza en el cliente, antes de contactar al servidor, así que no se crea ninguna sesión en la nube:

Cloud sessions cannot be created from a --restricted session: they would not enforce it.

Qué hacer:

• Ejecuta la tarea localmente en la sesión restringida
• Si controlas cómo se inició la sesión, inicia una nueva sesión de claude sin --restricted y crea la sesión en la nube desde allí

Antes de v2.1.248, Claude Code no tenía el flag --restricted; las versiones anteriores rechazan el propio flag con un error de opción desconocida.

Las sesiones en la nube están deshabilitadas por la política de tu organización

La política allow_remote_sessions de tu organización está desactivada, así que las sesiones en la nube y los comandos que las usan no están disponibles:

Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.

El mensaje aparece cuando creas una sesión en la nube desde la terminal y cuando envías un comando que necesita sesiones en la nube, como /teleport, /remote-env o /web-setup. Antes de v2.1.268, enviar uno de esos comandos devolvía Unknown command en su lugar.

Se trata de una política de la organización del lado del servidor, así que no se puede sobrescribir desde la configuración local, variables de entorno ni flags de la CLI.

Si Claude Code aún no ha cargado la política de tu organización o no puede obtenerla, esos comandos responden Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again. en su lugar.

Qué hacer:

• Pide a un Owner de tu organización que habilite las sesiones en la nube en la configuración de administración de Claude Code en claude.ai/admin-settings/claude-code
• Si el mensaje dice que no pudo verificar la política, revisa tu conexión de red, luego reinicia Claude Code e inténtalo de nuevo

El valor de `--json-schema` no es un JSON Schema válido

El esquema que pasaste a --json-schema en modo no interactivo falló la compilación de JSON Schema, así que claude termina con código 1 en lugar de ejecutar el prompt. Antes de v2.1.205, un esquema no válido producía una salida no estructurada sin ningún error, y cualquier esquema que usara la palabra clave format se trataba como no válido.

Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

El texto después de los segundos dos puntos es el diagnóstico del validador y nombra la palabra clave o la ubicación que falló. Los esquemas que usan la palabra clave format, como "format": "email", son válidos: Claude Code acepta format como anotación y no la aplica.

Claude Code ejecuta dos comprobaciones antes de la compilación del esquema: rechaza un valor que no sea JSON analizable con Error: --json-schema is not valid JSON, y un JSON válido que no sea un objeto con Error: --json-schema must be a JSON object.

Qué hacer:

• Corrige la parte del esquema que nombra el diagnóstico y vuelve a ejecutar el comando
• Consulta Get structured output para ver un esquema y un comando que funcionan

El archivo de configuración supera el límite de 2MiB

El archivo que pasaste a --settings es mayor que 2 MiB, así que claude termina con código 1 al iniciar en lugar de cargarlo. Antes de v2.1.214, Claude Code leía el archivo sin comprobar su tamaño, y un archivo de varios gigabytes o un archivo de dispositivo como /dev/zero hacía crecer la memoria sin límite.

Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

Claude Code rechaza de la misma forma una ruta de --settings que no sea un archivo normal: un dispositivo, FIFO o socket informa Error: Cannot use settings file (Not a regular file (device, FIFO, or socket)) seguido de la ruta, y un directorio informa un motivo EISDIR.

Qué hacer:

• Apunta --settings a un archivo de configuración JSON normal de menos de 2 MiB. Consulta Configuración para ver el formato.

El directorio actual ya no existe

Iniciaste claude desde un directorio que se eliminó o se movió después de que tu shell entrara en él, por ejemplo un worktree o un directorio temporal que otro shell eliminó. Claude Code no puede leer su directorio de trabajo, así que termina con código 1 antes de iniciar la sesión, tanto en modo interactivo como no interactivo. Antes de v2.1.239, Claude Code fallaba mostrando código fuente minificado del bundle y una traza ENOENT ... uv_cwd sin procesar en stderr en lugar de este mensaje.

The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

La causa y la solución son las mismas para ambas formas.

Cuando Claude Code no puede leer el directorio de trabajo por otro motivo, como un cambio de permisos, el mensaje nombra el código de error en su lugar: Can't read the current directory (EACCES). Start Claude Code from a different directory.

En macOS, EPERM para un directorio en ~/Desktop, ~/Documents, ~/Downloads o iCloud Drive suele significar que macOS está bloqueando el acceso de tu app de terminal a esa carpeta. Otros comandos que leen esa carpeta fallan de la misma forma: ls allí informa Operation not permitted, incluso con sudo.

Qué hacer:

• Cambia a un directorio que exista, como tu directorio home o el de tu proyecto, y vuelve a ejecutar claude
• Si el directorio se volvió a crear en la misma ruta, tu shell todavía mantiene el que se eliminó. Ejecuta cd "$PWD" o sal y vuelve a entrar en el directorio, y luego ejecuta claude de nuevo
• Para EPERM en macOS, cierra tu app de terminal con Cmd+Q, vuelve a abrirla, regresa a esa carpeta y ejecuta claude. Si ls en esa carpeta sigue fallando, abre System Settings > Privacy & Security > Files and Folders, activa la carpeta para tu app de terminal y vuelve a abrir la terminal

Directorio temporal rechazado o que no se puede crear

En macOS y Linux, Claude Code crea un directorio temporal privado al iniciar, claude-<uid>, dentro del directorio temporal del sistema o de la sobrescritura CLAUDE_CODE_TMPDIR. Cuando el directorio no se puede crear, o una entrada que ya existe en esa ruta no supera las comprobaciones de seguridad, Claude Code imprime el fallo en stderr y termina con código 1 en lugar de iniciar la sesión:

ENOSPC: no space left on device, mkdir '/tmp/claude-501'

Temp directory /tmp/claude-501 is not a directory (may be an attacker-planted symlink). Refusing to use it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is owned by uid 502, expected 501. Refusing to use it — another user may have pre-created it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

Qué hacer:

• Para ENOSPC, libera espacio en disco en el volumen que contiene el directorio temporal
• Para las formas Refusing to use it, elimina la entrada nombrada en sí, no aquello a lo que apunta un enlace, y vuelve a iniciar Claude Code; para la forma owned by uid, solo un administrador o ese usuario puede eliminarla
• Para is not readable, ejecuta chmod 0700 en el directorio nombrado, o elimínalo y vuelve a iniciar
• En cualquiera de estos casos, establece CLAUDE_CODE_TMPDIR en un directorio que controles y vuelve a iniciar Claude Code, sin tocar la ruta rechazada

No se pudo resolver el directorio a una ubicación real

Ejecutaste /add-dir para un subdirectorio de tu directorio de trabajo, y Claude Code no pudo resolver el directorio a su ubicación real.

Ya tienes acceso a los archivos de un subdirectorio del directorio de trabajo, así que /add-dir solo carga sus skills, comandos y agentes. Antes de cargarlos, Claude Code comprueba que la ubicación real del directorio, con los enlaces simbólicos resueltos, esté dentro del directorio de trabajo. Cuando Claude Code no puede resolver esa ubicación, no carga nada y muestra este mensaje:

packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

Qué hacer:

• Comprueba que la ruta nombre un directorio real dentro del directorio de trabajo y vuelve a ejecutar /add-dir
• El mensaje no cambia tu acceso a los archivos; solo informa que no se cargó el contenido de .claude/ del directorio

Antes de v2.1.261, este mensaje también aparecía para cada /add-dir <subdirectory> cuando el directorio de trabajo estaba en un montaje automático /net/<host>, donde Claude Code no resuelve rutas por diseño; el directorio estaba bien y reintentar no servía de nada.

Espacio de trabajo no confiable al iniciar Remote Control

Iniciaste el modo servidor de Remote Control con claude remote-control o su alias claude rc en un directorio en el que no has confiado, y el comando no pudo preguntarte si confiar en él. Por ejemplo, la entrada estándar o la salida estándar del comando no es una terminal porque una de ellas está redirigida o canalizada. El comando termina con código 1:

Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

Dos variantes que también comienzan con Error: Workspace not trusted. aparecen en una terminal demasiado pequeña para mostrar lo que activa confiar en el directorio, o en una que no informó su tamaño. Agranda la ventana o cambia a una ventana de terminal normal y vuelve a ejecutar claude rc.

En tu directorio home el mensaje es diferente, porque el diálogo de confianza del espacio de trabajo nunca guarda la confianza para el directorio home, así que aceptarlo allí no puede satisfacer esta comprobación. Antes de v2.1.214, el directorio home mostraba el mensaje anterior, cuyo consejo no puede funcionar allí.

Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

Si respondes n o presionas Enter en la pregunta Trust <directory>?, el comando imprime un mensaje Remote Control did not start que nombra el directorio y termina con código 1. Vuelve a ejecutar claude rc para responder y.

Qué hacer:

• Primero confía en el directorio desde una terminal: ejecuta claude rc allí y responde y, o ejecuta claude allí y acepta el diálogo de confianza del espacio de trabajo, y luego vuelve a ejecutar tu comando original
• En tu directorio home, cambia a un directorio de proyecto e inicia Remote Control allí

Antes de v2.1.284, el comando nunca preguntaba, ni siquiera en una terminal.

No se traslada a las sesiones que inicia Remote Control

Iniciaste Remote Control con un flag global de claude antes del verbo remote-control, uno que restringiría o configuraría las sesiones que inicia Remote Control, como --settings, --setting-sources, --permission-mode, --disallowed-tools o --mcp-config. Un flag colocado antes del verbo nunca llega a esas sesiones. En su lugar, Claude Code se niega a iniciar y nombra el flag:

Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

Claude Code no rechaza los flags globales que es inofensivo descartar, como --verbose, --model, o un --session-id o --plugin-dir inyectado por un wrapper: los ignora y Remote Control se inicia.

Claude Code también se niega a iniciar ante un flag global que todavía no reconoce como inofensivo, así que un flag agregado en una versión más reciente puede aparecer en este mensaje hasta que una versión posterior lo marque como inofensivo.

Qué hacer:

• Quita el flag de antes del verbo y pasa las opciones propias de Remote Control después de él; claude remote-control --help las enumera
• Cuando el flag rechazado es --permission-mode, ejecuta claude remote-control --permission-mode <mode> para establecer el modo de permisos de las sesiones que inicia Remote Control

Antes de v2.1.248, claude remote-control no aceptaba sus propios flags cuando iba primero un flag global, y el comando fallaba con un error unknown option.

claude import todavía no está disponible en esta compilación

Ejecutaste claude import, y Claude Code encontró el flujo de importación desactivado, así que el comando termina con código 1 en lugar de iniciar la importación. Antes de v2.1.222, una compilación con el flujo de importación desactivado trataba import como un prompt e iniciaba una sesión interactiva en lugar de imprimir este mensaje.

`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

Claude Code activa claude import mediante un feature flag que obtiene de Anthropic y almacena en caché en disco. Este mensaje significa que el valor en caché está desactivado. La causa suele ser una de las siguientes:

• No has iniciado una sesión desde la instalación, así que Claude Code todavía no ha obtenido el flag. El primer claude import puede imprimir esto incluso cuando la función está disponible para ti.
• Usas Claude Code a través de Amazon Bedrock, Agent Platform de Google Cloud, Microsoft Foundry o Claude Platform on AWS, o a través de un gateway de apps de Claude. Claude Code no obtiene feature flags en estas sesiones, así que claude import sigue sin estar disponible.
• Estableciste DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_GROWTHBOOK o CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, que desactivan la obtención de feature flags, así que claude import sigue sin estar disponible.

Qué hacer:

• En una instalación nueva, inicia claude, espera a que se cargue la sesión, sal y vuelve a ejecutar claude import
• Donde la obtención de feature flags sigue desactivada, prepara la configuración tú mismo: agrega servidores MCP con claude mcp add, y crea los archivos CLAUDE.md, los skills y comandos y los subagentes que quieras trasladar. El mensaje también nombra ~/.claude/settings.json. De la configuración que traslada claude import, ese archivo contiene solo el modo de permisos; Claude Code no lee servidores MCP desde él.

No se pudo leer la configuración de Claude Code

Ejecutaste claude import mientras Claude Code no podía analizar ~/.claude.json, el archivo donde almacena tu inicio de sesión y el estado de cada proyecto. El subcomando lee ese archivo para comprobar la disponibilidad, pero no muestra el diálogo de recuperación que muestra la sesión interactiva, así que termina con código 1. Antes de v2.1.222, claude import con un archivo de configuración ilegible iniciaba una sesión interactiva, cuyo diálogo de recuperación se encargaba del archivo.

Could not read Claude Code config — run `claude` with no arguments to recover it.

Qué hacer:

• Ejecuta claude sin argumentos. Claude Code detecta el archivo no válido y ofrece restablecerlo. Luego vuelve a ejecutar claude import.
• Para conservar las ediciones manuales que hayas hecho, corrige en su lugar la sintaxis JSON de ~/.claude.json en un editor y vuelve a ejecutar claude import

No se pudo importar un servidor desde Claude Desktop

Claude Code no pudo agregar uno de los servidores que seleccionaste en claude mcp add-from-claude-desktop. El comando igualmente importa los demás servidores seleccionados e imprime una línea por cada servidor que no pudo agregar. Antes de v2.1.205, el primer servidor que fallaba detenía la importación.

Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

El texto después del nombre del servidor es el motivo. El más común es la comprobación del nombre: Claude Desktop permite en los nombres de servidor caracteres, como espacios y puntos, que claude mcp restringe a letras, números, guiones y guiones bajos. Otros motivos incluyen una configuración de servidor que no supera la validación y un servidor bloqueado por la política de MCP de tu organización.

Qué hacer:

• Cambia el nombre del servidor en claude_desktop_config.json para que use solo letras, números, guiones y guiones bajos, y vuelve a ejecutar claude mcp add-from-claude-desktop
• Agrega ese servidor directamente con claude mcp add o claude mcp add-json con un nombre válido. Consulta Import MCP servers from Claude Desktop.

No se puede agregar un servidor MCP al alcance administrado

Ejecutaste claude mcp add o claude mcp add-json con --scope managed. Ese alcance contiene los servidores que tu organización proporciona mediante el ajuste administrado managedMcpServers. Claude Code los lee solo desde la configuración administrada, así que el comando no puede escribir un servidor en ese alcance.

Cannot add MCP server to scope: managed

Qué hacer:

• Agrega el servidor a un alcance en el que puedas escribir: local, user o project. Sin --scope, el comando usa local. Consulta MCP installation scopes
• Para proporcionar el servidor a todos los usuarios de tu organización, agrégalo a managedMcpServers en la configuración administrada que despliegas

No se puede agregar un servidor MCP cuando la configuración administrada permite solo servidores de plugins

Ejecutaste claude mcp add o claude mcp add-json mientras la configuración administrada de tu organización establece strictPluginOnlyCustomization en true o en una lista que incluye mcp. Con ese ajuste, Claude Code no carga servidores MCP desde ~/.claude.json ni .mcp.json, así que el comando termina con código 1 en lugar de guardar un servidor que nunca se cargaría:

Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.

claude mcp add-from-claude-desktop informa cada servidor que seleccionas como no importado, con este mensaje como motivo. /import informa este mensaje para cada servidor MCP que intenta agregar e igualmente importa los demás elementos que encontró.

Antes de v2.1.284, estos comandos guardaban el servidor e informaban éxito, y el servidor nunca se cargaba.

Qué hacer:

• Instala un plugin que proporcione el servidor
• Pide a tu administrador que distribuya el servidor en un plugin, o que lo proporcione mediante managedMcpServers si es un servidor HTTP o SSE remoto

No se puede leer .mcp.json

Un comando que lee el .mcp.json del proyecto, como claude mcp add o claude mcp add-json con --scope project, o claude mcp remove, encontró que el archivo de tu directorio actual no es un archivo normal o es mayor que 2 MiB, así que termina con este error en lugar de leer el archivo.

Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

Antes de v2.1.257, un FIFO en .mcp.json dejaba el comando esperando para siempre sin ninguna salida, y un enlace simbólico a un archivo de dispositivo como /dev/zero hacía crecer la memoria hasta que el proceso se terminaba.

Qué hacer:

• Revisa qué hay en .mcp.json en tu directorio actual. Reemplázalo por un archivo JSON normal con el formato de alcance de proyecto, o elimínalo, y vuelve a ejecutar el comando.

El servidor MCP no se guardó ni se eliminó

Ejecutaste claude mcp add, claude mcp add-json o claude mcp remove para un servidor en el alcance user o local. Ambos alcances se almacenan en ~/.claude.json, y el cambio no está en ese archivo cuando Claude Code lo vuelve a leer después de escribir. El comando termina con este error en lugar de su línea de éxito.

MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.

Después de una eliminación, el mensaje dice was not removed from y termina con then remove the server again. Para un servidor de alcance local, la ruta va seguida del directorio del proyecto al que pertenece la entrada, como (local scope for /path/to/project).

Antes de v2.1.283, claude mcp add, claude mcp add-json y claude mcp remove informaban éxito incluso cuando el cambio no llegaba al archivo.

Qué hacer:

• Haz que el archivo que nombra el mensaje se pueda escribir, o ejecuta el comando fuera del sandbox, y luego vuelve a ejecutar el mismo comando de agregar o eliminar.

Es posible que el servidor MCP no se haya guardado ni eliminado

Ejecutaste claude mcp add, claude mcp add-json o claude mcp remove para un servidor en el alcance user o local, y Claude Code no pudo volver a leer ~/.claude.json para confirmar el cambio. Es posible que el cambio esté o no esté en disco. El texto entre paréntesis es el error de esa lectura.

MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.

Después de una eliminación, el mensaje dice may not have been removed y termina con then remove the server again if it is still listed.

Antes de v2.1.283, los comandos informaban éxito incluso cuando no se podía confirmar el cambio.

Qué hacer:

• Ejecuta claude mcp get <name> para comprobar si el cambio está en disco. Para un servidor de alcance local, ejecútalo desde el directorio del proyecto al que pertenece el servidor, ya que el alcance local es por proyecto.
• Si el servidor falta después de agregarlo, o sigue en la lista después de eliminarlo, vuelve a ejecutar el mismo comando de agregar o eliminar.

El servidor está alojado por Anthropic y no admite OAuth local

Iniciaste un inicio de sesión para un servidor MCP cuya URL apunta a un host de conector alojado por Anthropic que se autentica mediante un proveedor de identidad de terceros. Estos hosts incluyen microsoft365.mcp.claude.com, gmail.mcp.claude.com y gcal.mcp.claude.com. Claude Code se niega a iniciar su flujo de OAuth local para estos hosts tanto desde el panel /mcp como desde claude mcp login, porque su inicio de sesión solo funciona a través de claude.ai.

"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

Qué hacer:

• Elimina tu entrada con claude mcp remove <name>, para que no pueda ocultar el conector de claude.ai en la misma URL
• Después de eliminarla, conecta el servicio en claude.ai/customize/connectors, con la sesión iniciada en la cuenta que usas en Claude Code. Una vez conectado, el conector aparece automáticamente en Claude Code si tu método de autenticación activo es un inicio de sesión con suscripción de claude.ai

El servidor rechazó el encabezado Authorization generado por el headersHelper configurado

Un servidor MCP cuyo headersHelper proporciona el encabezado Authorization respondió a la conexión con HTTP 401 o 403, así que Claude Code informa que la conexión falló. Como el helper proporciona el encabezado Authorization, Claude Code no recurre a OAuth para el servidor:

Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

Claude Code vuelve a ejecutar el helper en cada intento de conexión, así que un reintento después de un rechazo transitorio, como una condición de carrera en la rotación de tokens, puede tener éxito con una credencial nueva.

Qué hacer:

• Ejecuta tú mismo el comando headersHelper de la misma forma en que lo ejecuta Claude Code: desde el directorio en el que Claude Code lo ejecuta, con las variables de entorno que Claude Code establece para él, y sin las variables de credenciales que Claude Code elimina para un servidor de un .mcp.json de proyecto, un plugin o un archivo de agente de proyecto. Comprueba que imprima un valor de Authorization que el endpoint del servidor acepte
• Después de corregir el helper o el origen de su credencial, selecciona el servidor en /mcp y elige Reconnect

Antes de v2.1.248, Claude Code ejecutaba el descubrimiento de OAuth para un servidor cuyo helper proporcionaba el encabezado Authorization. Ese descubrimiento podía fallar con Incompatible auth server: does not support dynamic client registration en lugar de informar la credencial rechazada.

No se encontró la herramienta MCP de solicitud de permisos

La herramienta que pasaste a --permission-prompt-tool no estaba entre las herramientas MCP conectadas cuando la ejecución necesitó por primera vez una decisión de permisos, ya sea porque su servidor nunca se conectó o porque ningún servidor conectado expone una herramienta con ese nombre. Claude Code igualmente envía tu prompt: la ejecución no interactiva termina con este error, y código de salida 1, en la primera llamada a herramienta, así que no produce ninguna respuesta aunque la solicitud se haya realizado. Antes del primer prompt, Claude Code espera a que ese servidor se conecte durante, como máximo, el tiempo de espera de conexión por servidor de 30 segundos establecido por MCP_TIMEOUT. Antes de v2.1.206, el inicio no esperaba a que el servidor terminara de conectarse, así que un servidor sano pero lento al iniciar también producía este error.

Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

La lista después de Available MCP tools: nombra las herramientas MCP que estaban conectadas.

Qué hacer:

• Comprueba que el servidor se inicie y permanezca conectado: ejecuta claude mcp list en el mismo directorio y confirma que el servidor aparece como conectado
• Confirma que el nombre de la herramienta coincida con el nombre mcp__<server>__<tool> que expone el servidor
• Si el servidor necesita más de 30 segundos para iniciar, aumenta MCP_TIMEOUT

El puerto de callback de OAuth ya está en uso

Cuando inicias sesión en un servidor MCP remoto con OAuth, Claude Code inicia un listener local para recibir el callback de inicio de sesión. Si otro proceso ocupa el puerto que necesita ese listener, el inicio de sesión falla con este mensaje. Esto sucede sobre todo con un puerto de callback fijo establecido mediante la variable MCP_OAUTH_CALLBACK_PORT o --callback-port, ya que sin uno Claude Code elige un puerto disponible.

OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

En Windows, el comando sugerido es netstat -ano | findstr :<port> en su lugar.

Qué hacer:

• Ejecuta el comando del mensaje para encontrar el proceso que ocupa el puerto, y detenlo o espera a que termine
• Si otro programa necesita ese puerto de forma permanente, registra un URI de redirección diferente en el servidor y establece su puerto con MCP_OAUTH_CALLBACK_PORT o --callback-port, el que uses
• Luego vuelve a iniciar el inicio de sesión, por ejemplo seleccionando el servidor en /mcp

No hay puertos disponibles para la redirección de OAuth

Cuando inicias sesión en un servidor MCP remoto con OAuth, Claude Code inicia un listener local para recibir el callback de inicio de sesión. El inicio de sesión falla con este mensaje cuando Claude Code no puede vincular un puerto local para él. Algo en la máquina le impide escuchar en 127.0.0.1, por ejemplo software de seguridad o una política de sandbox que deniega los listeners locales.

No available ports for OAuth redirect

Antes de v2.1.268, Claude Code no recurría a un puerto asignado por el sistema operativo, así que el mensaje también aparecía cuando solo los puertos que él mismo elegía no se podían vincular. Eso puede ocurrir en hosts Windows donde Hyper-V reserva rangos de puertos que cubren los puertos entre los que elige Claude Code.

Qué hacer:

• Comprueba si algún software de seguridad o una política de sandbox impide que los procesos escuchen en 127.0.0.1, y permite que Claude Code vincule un puerto local
• Luego vuelve a iniciar el inicio de sesión, por ejemplo seleccionando el servidor en /mcp

/security-review falla sin origin/HEAD

/security-review construye el contexto de su revisión generando el diff de tu rama contra origin/HEAD, la referencia local que registra qué rama es la predeterminada en tu remoto origin. Cuando esa referencia no existe, los comandos de git que recopilan el diff fallan y la revisión se detiene antes de empezar.

Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]
fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

Es posible que el mensaje cite git log u otro git diff en su lugar. Git crea origin/HEAD solo cuando el remoto anuncia una rama predeterminada y tu refspec de fetch la cubre, lo que ocurre con un git clone completo de un remoto con commits. La referencia falta en estas configuraciones:

• Un checkout de una sola rama o de CI, que obtiene un refspec demasiado limitado
• Un remoto cuyo HEAD del lado del servidor apunta a una rama que nadie ha subido
• Un repositorio sin remoto origin, o uno del que nunca hiciste fetch

Claude Code muestra el mismo error para cualquier skill que inyecte contexto dinámico, y un comando inyectado que falla aborta la invocación de ese skill. Dos mensajes hermanos se producen antes de que el comando llegue a ejecutarse:

• Shell command permission check failed for pattern "...": la comprobación de permisos del comando no lo permitió. Permission checks on injected commands explica qué resultados abortan en cada modo de permisos y cómo aprobar previamente un comando con allowed-tools
• Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found: el frontmatter del skill exige bash en una máquina que no lo tiene. Instala Git for Windows o cambia el frontmatter a shell: powershell. Consulta How injected commands run

Qué hacer:

• Crea la referencia nombrando la rama predeterminada de tu remoto: git remote set-head origin <default-branch>. Esto funciona siempre que exista la referencia de seguimiento local origin/<default-branch>. Si no existe, como en los clones de una sola rama, primero obtén la rama: ejecuta git remote set-branches --add origin <branch>, luego git fetch origin, y luego vuelve a ejecutar el comando set-head. Vuelve a ejecutar /security-review.
• Si prefieres no nombrar la rama, ejecuta git fetch origin y luego git remote set-head origin --auto, que pregunta al remoto cuál es su rama predeterminada. Falla con error: Cannot determine remote HEAD cuando el remoto no anuncia ninguna rama predeterminada, porque está vacío o su HEAD apunta a una rama que nadie ha subido; en ese caso, nombra la rama explícitamente. Falla con error: Not a valid ref cuando tu clon no obtiene esa rama; primero amplía el refspec como se indicó arriba.
• Si el repositorio no tiene remoto, agrega uno con git remote add origin <url> y haz fetch antes de crear la referencia. Si el remoto está vacío, primero sube tu rama con git push -u origin HEAD y nombra esa rama en el comando set-head; origin/HEAD apunta entonces a la rama que acabas de subir, así que /security-review ve un diff vacío hasta que la rama diverja de ella.

Se debe proporcionar una entrada al usar `--print`

claude sin argumentos necesita que stdout sea una terminal para iniciar la interfaz interactiva. Cuando stdout está redirigido, o la consola no es una terminal real, como PowerShell ISE y algunos paneles de salida de IDE, claude se ejecuta de forma no interactiva en su lugar. Es el mismo modo que claude -p, que requiere un prompt, así que el mensaje nombra --print aunque no hayas pasado el flag. Pasar -p/--print sin prompt y sin nada canalizado por stdin produce el mismo error en cualquier lugar.

Error: Input must be provided either through stdin or as a prompt argument when using --print

Qué hacer:

• Para uso interactivo, ejecuta claude en una terminal real: Windows Terminal o la consola de PowerShell en lugar de ISE, y la terminal integrada de tu IDE en lugar de un panel de salida
• Para un uso puntual, pasa el prompt: claude -p "your question", o canalízalo con echo "your question" | claude -p

La entrada contenía solo espacios en blanco

En modo no interactivo, Claude Code rechaza un prompt compuesto únicamente por espacios, tabulaciones o saltos de línea en lugar de enviarlo, porque la API rechaza los mensajes sin texto visible. El mensaje que ves depende de dónde vino el prompt en blanco:

• Argumento de prompt o stdin canalizado para claude -p: claude termina con Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print
• Mensaje enviado a una sesión en ejecución de --input-format stream-json o del Agent SDK: Claude Code termina el turno sin llamar al modelo y la sesión sigue siendo utilizable. El rechazo llega como un mensaje informativo y como el texto de resultado del turno: Blank prompt — the message was only whitespace, so nothing was sent to the model.

Antes de v2.1.229, Claude Code enviaba el mensaje de solo espacios en blanco a la API, que rechazaba la solicitud con un error 400.

Qué hacer:

• Incluye texto visible en el prompt. Si un script construye el prompt a partir de una variable o un archivo, comprueba que el origen no esté vacío antes de llamar a Claude Code.

La entrada stream-json contenía más de 256M caracteres sin salto de línea

Tu programa envió más de 268,435,456 caracteres por stdin sin un salto de línea a una ejecución de claude -p --input-format stream-json, así que Claude Code imprime este error en stderr y termina con código 1 en lugar de almacenar más entrada en el búfer. El mensaje expresa ese límite como 256M. Antes de v2.1.257, Claude Code almacenaba esa entrada en el búfer sin límite, haciendo crecer la memoria hasta que el proceso fallaba o se terminaba.

Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

Una entrada tan larga sin salto de línea suele significar que el productor no es en absoluto un productor de stream-json, como un archivo binario o una salida de registro en texto plano canalizados por accidente. Un solo mensaje que supere el límite falla la misma comprobación.

Qué hacer:

• Revisa qué se canaliza a stdin. Con --input-format stream-json, cada mensaje debe ser una línea JSON terminada en salto de línea
• Para enviar texto plano en su lugar, quita --input-format stream-json; claude -p lee de forma predeterminada un prompt en texto plano desde stdin

Comando desconocido

En una sesión de terminal interactiva, enviaste un nombre con / que no coincide con ningún comando de esta sesión, así que Claude Code informa el nombre en lugar de ejecutar nada:

Unknown command: /hepl. Did you mean /help?

Claude Code sugiere el nombre de comando o alias más cercano que el menú muestra en esta sesión. Cuando no hay nada cercano, el mensaje termina después del nombre. La causa suele ser una de las siguientes:

• Un error tipográfico, como /hepl en lugar de /help. How the command menu matches what you type explica cómo elegir una coincidencia cercana antes de enviar
• Un comando que existe pero no está disponible en esta sesión porque no se cumple un requisito, como tu plataforma, tu plan o tu método de autenticación. Las entradas de solución de problemas de /web-setup y /schedule explican dos casos comunes. Algunos comandos responden con su propio mensaje cuando la política de tu organización los deshabilita, como Cloud sessions are disabled by your organization's policy
• Un comando de un plugin o de un servidor MCP que no está instalado o conectado en esta sesión

Claude Code responde de esta forma a un nombre con / sin coincidencia solo en una sesión de terminal interactiva. En todas las demás sesiones, envía el prompt a Claude como un mensaje normal, con una nota de que el comando no se ejecutó y una lista de los comandos que Claude puede ejecutar en la sesión. Esas sesiones incluyen:

• Ejecuciones con -p
• Aplicaciones del Agent SDK
• La pestaña Code de la app de escritorio
• El panel de chat de la extensión de VS Code
• Sesiones en la nube y rutinas

Para un comando integrado que no puede ejecutarse en una de esas sesiones, Claude Code igualmente responde que el comando no está disponible en lugar de enviarlo a Claude. Antes de v2.1.274, solo las sesiones en la nube y las rutinas enviaban a Claude un nombre sin coincidencia. Antes de v2.1.273, también respondían Unknown command.

Claude Code no trata como comando cada prompt que comienza con /. Envía el prompt a Claude como un mensaje normal cuando la primera palabra después de / comienza con un signo de puntuación, como el /-- que abre un comentario de documentación de Lean, o es una ruta como /var/log/syslog.

Antes de v2.1.236, si presionabas Enter mientras el menú de comandos mostraba una coincidencia cercana al nombre que escribiste, Claude Code ejecutaba esa coincidencia, así que un error tipográfico como /hepl ejecutaba /help en lugar de producir este mensaje.

Qué hacer:

• Ejecuta el nombre sugerido, o escribe / seguido de parte del nombre para ver qué está disponible en esta sesión
• Si Claude Code informa como desconocido un comando documentado, revisa su fila en la referencia de comandos para ver el requisito que indica

El diff es demasiado grande para ultrareview

El diff entre tu rama y la rama base, incluidos los cambios sin commit y los cambios preparados, supera los límites de tamaño de un ultrareview, así que /code-review ultra y el subcomando claude ultrareview rechazan la revisión antes de que se inicie la sesión en la nube. Una revisión rechazada no consume una ejecución gratuita ni factura créditos de uso. El mensaje nombra los límites vigentes, el tamaño de tu diff y los archivos que aportan más líneas modificadas. Antes de v2.1.216, el mensaje mostraba solo las estadísticas del diff sin procesar.

Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

Revisar un pull request aplica los mismos límites; esa forma del mensaje comienza con PR #<N> is too large for ultrareview y nombra el número de archivos y líneas del PR.

Qué hacer:

• Pasa una rama base más cercana a tu trabajo, como /code-review ultra develop, para que la revisión cubra solo el diff contra esa rama
• Divide el cambio en ramas más pequeñas y revisa cada una. Los archivos que nombra el mensaje aportan más líneas modificadas, así que empieza por moverlos a su propia rama.

No se pudo encontrar el merge-base con la rama base

/code-review ultra y el subcomando claude ultrareview revisan el diff entre tu rama y una rama base, lo que requiere un commit que ambas compartan. Cuando git merge-base no encuentra ninguno, Claude Code rechaza la revisión antes de que se inicie la sesión en la nube. En un clon que Claude Code puede verificar como completo, con al menos una rama, recurre a revisar todos los archivos con seguimiento en lugar de rechazarla. Ves este rechazo cuando no se encuentra la rama base en absoluto, cuando Claude Code no puede verificar que tu clon esté completo, o en el caso poco frecuente de un repositorio donde el diff de todo el árbol no es posible, como con el formato de objetos SHA-256.

Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

La sugerencia después de la primera oración depende de lo que Claude Code observó:

• No pasaste una rama base: Claude Code comparó contra la rama predeterminada del repositorio y sugiere pasar tu rama base explícitamente, como en el ejemplo anterior
• Pasaste una rama base que ya estaba en tu clon: la sugerencia dice Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)
• Pasaste una rama base que no estaba en tu clon: Claude Code la obtuvo de origin antes de comparar. La sugerencia dice <branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`); cuando Claude Code no puede determinar si tu clon es superficial, sugiere git fetch --unshallow origin en su lugar. Antes de v2.1.221, la sugerencia proponía git fetch --unshallow origin para toda rama base obtenida, y en un clon completo ese comando falla con fatal: --unshallow on a complete repository does not make sense.

Qué hacer:

• Si otra rama es tu verdadera base, pásala explícitamente: /code-review ultra <branch>
• Si es posible que tu clon no tenga el historial completo, ejecuta git fetch --unshallow origin y vuelve a ejecutar la revisión

Tu checkout no tiene ramas

Un checkout puede tener commits pero no ramas: si ejecutas git init seguido de git fetch <url> y git checkout FETCH_HEAD, obtienes un HEAD desacoplado sin referencias. Claude Code empaqueta tu repositorio como un bundle de git para subirlo para un ultrareview, y no puede empaquetar un repositorio que no tenga ramas ni otras referencias, así que /code-review ultra y el subcomando claude ultrareview rechazan la revisión antes de que se inicie la sesión en la nube.

Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

Antes de v2.1.221, Claude Code intentaba revisar todos los archivos con seguimiento de este checkout, y la subida fallaba.

Qué hacer:

• Crea una rama en tu commit actual con git checkout -b <name> y vuelve a ejecutar la revisión

No hay ninguna cuenta de GitHub conectada a tu cuenta de Claude

Ejecutaste /code-review ultra <PR#> o claude ultrareview <PR#>, y antes de crear la sesión en la nube Claude Code pregunta al servidor si la cuenta de GitHub conectada a tu cuenta de Claude puede acceder al repositorio del PR. No hay ninguna cuenta conectada, o la conexión expiró, así que la clonación en la nube fallaría y Claude Code rechaza el inicio. Claude Code no consume una ejecución gratuita ni factura créditos de uso por un inicio rechazado.

Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

Cuando /web-setup no está disponible en tu sesión, el mensaje nombra solo el enlace de claude.ai.

Qué hacer:

• Ejecuta /web-setup para conectar tu inicio de sesión de la CLI de GitHub a tu cuenta de Claude, o conecta una cuenta en claude.ai/connect-github
• Vuelve a ejecutar la revisión un minuto después de conectarte

Antes de v2.1.248, Claude Code no comprobaba esto antes del inicio.

Tu cuenta de GitHub conectada no puede ver el repositorio

Ejecutaste /code-review ultra <PR#> o claude ultrareview <PR#>, y la cuenta de GitHub conectada a tu cuenta de Claude no puede leer el repositorio del PR, así que la clonación en la nube fallaría y Claude Code rechaza el inicio. Claude Code no consume una ejecución gratuita ni factura créditos de uso por un inicio rechazado.

Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

Cuando /web-setup no está disponible en tu sesión, el mensaje nombra solo la instalación de la app.

Qué hacer:

• Si tu CLI gh local puede leer el repositorio, ejecuta /web-setup para conectar ese inicio de sesión a tu cuenta de Claude
• Vuelve a ejecutar la revisión después del cambio

Antes de v2.1.248, Claude Code no comprobaba esto antes del inicio.

La comprobación previa de la GitHub App falló de forma transitoria

Iniciaste una sesión en la nube desde un repositorio local, y dos pasos fallaron a la vez. Claude Code no pudo crear ni subir el bundle de tu repositorio. Antes de la subida, comprobó si el servicio en la nube puede clonar el repositorio desde GitHub y, en lugar de una respuesta definitiva, esa comprobación terminó en un error que un reintento podría resolver, como un error de red, un tiempo de espera agotado o un error temporal del servidor. El mensaje completo comienza con lo que detuvo el bundle, por ejemplo Could not upload repo bundle (<error>), y termina con la oración de la comprobación previa:

Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

Qué hacer:

• Vuelve a ejecutar el comando después de un momento. Cuando la comprobación de GitHub tiene éxito, Claude Code puede iniciar la sesión desde un clon de GitHub, así que la subida fallida ya no bloquea el inicio
• Si los reintentos siguen fallando, el comienzo del mensaje nombra lo que detuvo la subida. Cuando esa causa es algo que puedes corregir, corrígela para que la sesión pueda iniciarse desde tu repositorio local

Antes de v2.1.251, Claude Code terminaba el mensaje con Please set up GitHub on https://claude.ai/code incluso cuando la comprobación de GitHub fallaba solo de forma transitoria, y un consejo de configuración no puede resolver un fallo transitorio.

La subida del repositorio no puede seguir un ajuste de git

Iniciaste una sesión en la nube que sube tu repositorio local, o un ultrareview de una rama, y la subida no puede seguir uno de los ajustes de git que deciden qué reglas de atributos se aplican a tus archivos. Si la subida continuara y omitiera una regla, un archivo que git transforma antes de almacenarlo, como uno que un filtro clean cifra, podría llegar a la nube tal como está en disco. En su lugar, Claude Code rechaza la subida y no se sube nada:

Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.

El mensaje nombra el ajuste y dónde está establecido, y termina con la solución para el caso que encontraste. El mismo rechazo aparece para core.attributesFile y attr.tree, cada uno con su propia solución.

El mensaje puede nombrar un archivo de configuración que tu configuración de git incorpora mediante una directiva include o includeIf, incluso cuando la condición de esa directiva no se aplica a este repositorio.

Qué hacer:

• Aplica la solución de la última oración del mensaje

GitHub no está conectado a tu cuenta de Claude

Iniciaste una sesión en la nube desde tu repositorio local, por ejemplo con /autofix-pr. No hay ninguna cuenta de GitHub conectada a tu cuenta de Claude, o la conexión expiró, así que Claude Code rechaza el inicio:

GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

Cuando creas una rutina con /schedule, el mismo mensaje aparece como una nota de configuración que nombra el repositorio; la nota no impide crear la rutina.

Qué hacer:

• Ejecuta /web-setup para conectar tu inicio de sesión de la CLI de GitHub a tu cuenta de Claude, o conecta una cuenta en claude.ai/connect-github. Consulta GitHub authentication options para ver en qué se diferencian ambas opciones.
• Vuelve a ejecutar el comando un minuto después de conectarte

Antes de v2.1.268, Claude Code informaba esto como un fallo temporal de la comprobación de la Claude GitHub App y sugería reintentar o instalar la app; ninguna de las dos cosas conecta una cuenta de GitHub.

Se necesita autorización de inicio de sesión único

Ejecutaste /install-github-app y elegiste un repositorio cuya organización exige el inicio de sesión único SAML. Antes de la configuración, Claude Code comprueba tu acceso al repositorio con la CLI de GitHub, y GitHub rechazó esa comprobación porque tu token de gh todavía no está autorizado para la organización. El asistente muestra la advertencia con los pasos para autorizar:

Single sign-on authorization needed
<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.

Qué hacer:

• Vuelve a autorizar tu inicio de sesión de la CLI de GitHub con los alcances repo y workflow ejecutando gh auth refresh -h github.com -s repo,workflow, y autoriza la organización cuando GitHub solicite el inicio de sesión único
• Si te autenticas con un token de acceso personal en GH_TOKEN, abre github.com/settings/tokens, selecciona Configure SSO en el token y autoriza la organización
• Vuelve a ejecutar /install-github-app

Antes de v2.1.273, Claude Code mostraba en su lugar la advertencia Admin permissions required para esta condición.

No se pudo reanudar la conversación

Claude Code no pudo leer ni procesar la transcripción guardada de la sesión que seleccionaste en el selector de claude --resume, así que termina el proceso en lugar de continuar en un estado parcialmente cargado. El mensaje incluye el comando para reintentar:

Failed to resume the conversation.
Run claude --resume <session-id> to retry, or claude to start a new session.

Claude Code termina con código 1 después de mostrar el mensaje. El selector /resume dentro de una sesión en ejecución informa Failed to resume conversation en la conversación, y tu sesión actual sigue ejecutándose. Antes de v2.1.216, una reanudación fallida desde el selector de claude --resume se quedaba indefinidamente en el indicador giratorio Resuming conversation… en lugar de mostrar este mensaje.

Qué hacer:

• Ejecuta claude --resume <session-id> con el ID de sesión del mensaje para reintentar
• En una versión anterior a v2.1.285, si el reintento falla de la misma forma, ejecuta claude update y vuelve a reanudar. Esas versiones hacen fallar la reanudación cuando la transcripción guardada contiene una entrada que no pueden leer.
• Si el reintento vuelve a fallar, ejecuta claude para iniciar una nueva sesión

No conversation found with the session ID

Pasaste un ID de sesión a claude --resume <session-id> y ninguna transcripción guardada coincidió con él:

No conversation found with session ID: <session-id>

Claude Code sale con código 1 después de mostrar el mensaje. Claude Code busca primero en el proyecto actual y luego en todos los demás proyectos de esta máquina el ID. Antes de v2.1.223, la búsqueda se detenía en el directorio del proyecto actual y sus worktrees de git, así que debías reanudar desde el directorio en el que la sesión trabajó por última vez.

Causas comunes:

• ID mal escrito: para una ejecución no interactiva, el ID es el campo session_id de la salida de --output-format json
• Transcripción eliminada: Claude Code elimina las transcripciones después del período de retención, 30 días de forma predeterminada, siguiendo las reglas de limpieza por retención
• Máquina diferente: Claude Code almacena las transcripciones localmente, así que reanuda la sesión en la máquina donde se ejecutó
• Copias duplicadas: si copiaste un directorio de proyecto dentro de ~/.claude/projects de modo que dos transcripciones tienen el mismo ID, Claude Code muestra este mensaje en lugar de reanudar una de las copias arbitrariamente

Qué hacer:

• Para una sesión interactiva, abre el selector de sesiones con claude --resume y presiona Ctrl+A para ampliarlo a todos los proyectos de esta máquina; luego selecciona la sesión
• Las sesiones creadas con claude -p o con el Agent SDK no aparecen en el selector, así que vuelve a comprobar el ID con el session_id que imprimió tu ejecución original

Windows reported an error (EBADF) when Claude Code read this session's transcript file

Reanudaste una sesión en Windows, su archivo de transcripción guardado se abrió con normalidad y luego la lectura falló con el error del sistema EBADF. El error del sistema no indica por qué falló la lectura, así que el mensaje sugiere causas probables y qué intentar:

Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

El mensaje aparece después de la línea de error del propio comando, como Failed to resume session <session-id>. Un comando claude --resume o claude -p sale con código 1 después de mostrarlo. Después de /resume dentro de una sesión, tu sesión actual sigue ejecutándose.

Qué hacer:

• Excluye la carpeta que contiene tus transcripciones de sesión del software que escanea o intercepta lecturas de archivos, como herramientas de seguridad, cifrado o administración de endpoints. Las transcripciones se encuentran en %USERPROFILE%\.claude\projects de forma predeterminada, o en el directorio que indique CLAUDE_CONFIG_DIR
• Si no puedes agregar una exclusión, agrega Claude Code a las aplicaciones permitidas de ese software
• Reanuda la sesión de nuevo

Antes de v2.1.282, el error no venía acompañado de ninguna explicación: claude --resume <session-id> terminaba en Failed to resume session <session-id>, y una ejecución con -p imprimía solo el texto del error del sistema, como Failed to resume session: EBADF: bad file descriptor, read.

Cannot switch renderers in this session

Cuando cambias de renderizador, Claude Code reinicia su proceso. Ejecutaste /tui en una sesión que Claude Code se niega a reiniciar, así que no cambia y no guarda nada. El mensaje que ves te indica la causa:

• Cannot switch renderers while work is running in the background: tienes trabajo en segundo plano en ejecución que un reinicio abandonaría, como un shell en segundo plano o un subagente. Espera a que el trabajo termine o detenlo con /tasks, y luego ejecuta /tui fullscreen o /tui default de nuevo
• Cannot switch renderers in this session: la sesión tiene restricciones que Claude Code no puede pasar al proceso reiniciado. Antes de v2.1.234, Claude Code reiniciaba de todos modos y la sesión relanzada se ejecutaba sin ellas

En el mensaje de restricciones, la parte entre paréntesis nombra las restricciones que encontró Claude Code:

Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

Cada motivo que el mensaje puede mostrar entre paréntesis:

• launch flags: a custom system prompt, a tool allowlist, or restricted settings: iniciaste la sesión con un flag que Claude Code no vuelve a pasar al proceso reiniciado. Estos flags incluyen --system-prompt, --system-prompt-file, --append-system-prompt-file, una lista de herramientas permitidas con --tools, --setting-sources y --permission-prompt-tool
• permission rules set for this session only: una actualización de permisos desde un hook o un llamador del SDK agregó reglas de denegación o de consulta con el destino session. Las reglas de permiso con alcance de sesión no provocan el rechazo. Un reinicio las descarta y Claude Code vuelve a pedir permiso en su lugar
• ask-before-running rules with no command-line form: una actualización de permisos desde un hook o un llamador del SDK agregó reglas de consulta junto con las reglas que Claude Code vuelve a pasar como --allowed-tools y --disallowed-tools. No existe ningún flag para las reglas de consulta
• permission rules a command line cannot carry intact y added directories a command line cannot carry intact: una actualización de permisos agregó una regla o una ruta de directorio a mitad de la sesión. La línea de comandos del proceso reiniciado no puede transportar su texto como el mismo valor

Qué hacer:

• En una sesión iniciada sin esas restricciones, ejecuta /tui fullscreen, o /tui default para volver atrás. Claude Code guarda ahí el ajuste tui

Couldn't open Claude Desktop

Ejecutaste /desktop o su alias /app en una sesión, o claude --desktop en tu shell, y el comando del sistema que Claude Code usa para abrir Claude Desktop falló. Después de /desktop, la sesión permanece en la terminal; claude --desktop imprime el mensaje sin el prefijo Error: y sale con estado 1.

El texto entre paréntesis nombra el comando que falló, con su estado de salida y la primera línea de su salida de error cuando los produjo. En macOS ese comando es open, como en este ejemplo; en Windows es rundll32:

Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

Qué hacer:

• Abre Claude Desktop tú mismo y luego ejecuta /desktop o claude --desktop de nuevo
• Para leer la salida de error completa del comando que falló, activa el registro de depuración con /debug y ejecuta /desktop de nuevo, o ejecuta claude --desktop --debug-file <path>, y luego revisa el registro de depuración

Antes de v2.1.285, el mensaje terminaba con Open Claude Desktop and run /desktop again. Antes de v2.1.275, era Failed to open Claude Desktop. Please try opening it manually. y no indicaba qué había fallado.

/terminal-setup dejó tu keymap de Zed sin cambios

Ejecutaste /terminal-setup en Zed, y Claude Code no pudo completar la actualización de tu keymap.json de Zed, así que dejó el archivo como estaba.

Cada mensaje nombra la ruta de tu keymap y termina con el bloque de atajo de teclado que debes agregar tú mismo:

Couldn't update your Zed keymap, so it was left unchanged.
To add the binding yourself, add this block to the keymap array in <path to keymap.json>:
{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

La primera línea del mensaje nombra la causa:

• Couldn't read your Zed keymap, so it was left unchanged.: Claude Code no pudo leer el archivo, por ejemplo debido a los permisos del archivo
• Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.: el archivo se leyó bien, pero no se analiza como un array de bloques de atajos de teclado, incluso permitiendo comentarios // y comas finales
• Couldn't back up your Zed keymap; not modifying it.: Claude Code no pudo copiar el archivo a una copia de seguridad .bak junto a él, así que no cambió nada
• Couldn't update your Zed keymap, so it was left unchanged.: el resultado combinado no se verificó como un keymap válido que contenga el atajo, así que Claude Code lo descartó en lugar de escribirlo. Un bloque de atajos de teclado con una clave duplicada puede causar esto

Qué hacer:

• Copia el bloque del mensaje en el array de nivel superior de tu keymap.json, en la ruta que indica el mensaje
• Para isn't a readable list of keybindings, corrige el error de sintaxis o haz que el valor de nivel superior del archivo sea un array, y luego ejecuta /terminal-setup de nuevo

Antes de v2.1.247, /terminal-setup no podía analizar un keymap de Zed que usara comentarios // o comas finales, y reemplazaba el archivo completo solo con su propio atajo mientras informaba que el atajo estaba instalado. Para restaurar un keymap que una versión anterior reemplazó, usa el archivo de copia de seguridad .bak descrito en Introducir prompts de varias líneas.

Skill usage reports are not available on this connection

Ejecutaste /skill-doctor a través de Remote Control, desde tu teléfono o navegador. Claude Code no envía el informe de uso de skills a través de Remote Control y, en su lugar, responde con este mensaje:

Skill usage reports are not available on this connection.

Qué hacer:

• Ejecuta /skill-doctor en la terminal de la máquina donde se está ejecutando la sesión, o ejecuta claude -p "/skill-doctor" ahí

Custom output styles can't be selected over Remote Control

Ejecutaste /output-style desde la aplicación móvil o la web mediante Remote Control, o el comando llegó en un mensaje retransmitido a la sesión. Como ese turno podría no provenir del propietario de la cuenta, Claude Code solo lista y selecciona estilos integrados en él, y agrega este aviso siempre que el comando lista los estilos o no reconoce el nombre que indicaste. El nombre de un estilo personalizado recibe la misma respuesta que un nombre que no existe:

Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

Qué hacer:

• Elige un estilo integrado, por ejemplo /output-style concise
• Para usar un estilo personalizado, establece outputStyle en el .claude/settings.local.json del proyecto, o ejecuta /output-style <style> en la propia terminal de la sesión si tiene una

Output styles are saved to local settings which this session doesn't load

Intentaste cambiar de estilo de salida con /output-style <style> o /config outputStyle=<style> en una sesión cuyas fuentes de configuración excluyen local. Algunos ejemplos son una sesión del Agent SDK cuyo settingSources omite "local" y una sesión de la CLI iniciada con un valor de --setting-sources que omite local. Ambos comandos guardan el estilo en .claude/settings.local.json, un archivo que una sesión así nunca vuelve a leer, por lo que Claude Code se niega en lugar de escribir un ajuste que no tendría ningún efecto:

Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.

Qué hacer:

• Agrega local a las fuentes de configuración de la sesión y vuelve a cambiar el estilo
• Establece la clave outputStyle en un archivo de configuración que la sesión sí cargue, como .claude/settings.json en el proyecto o ~/.claude/settings.json. En el SDK de TypeScript, establece outputStyle dentro del objeto settings en línea; consulta Activar un estilo de salida

/recap only runs when you ask for it yourself

La solicitud de /recap no provino de tu propia entrada. Llegó en un mensaje retransmitido a la sesión desde un hilo de Slack, Teams o de un proyecto, o en un prompt que envió una rutina u otro programa.

Un mensaje retransmitido recibe el aviso incluso cuando lo escribiste tú mismo. Claude Code no puede saber si un mensaje retransmitido o automatizado provino de la persona cuya cuenta ejecuta la sesión, así que responde con este aviso en lugar de un resumen:

/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.

Un /recap que pasas a claude -p, o que tu propia aplicación del Agent SDK envía a una sesión que inició, cuenta como tu propia entrada.

Qué hacer:

• Abre la sesión tú mismo y ejecuta /recap ahí: en su terminal, en la aplicación de escritorio o la aplicación móvil, en claude.ai/code o a través de Remote Control
• Si lo envió una rutina u otro programa, elimina /recap de ese prompt

Errores de plugins

Estos errores provienen de la configuración de plugins y marketplace. Para problemas de plugins que no producen uno de los mensajes en esta página, como una URL de marketplace que no carga o un plugin que se instala pero no aparece, consulte Solución de problemas de plugins.

plugin eval is currently in early access

Ejecutó claude plugin eval o claude plugin eval init y salió con código 1 con uno de estos mensajes antes de hacer nada:

`plugin eval` is currently in early access

`plugin eval` is currently unavailable

El primer mensaje significa que su compilación es anterior a v2.1.269, la primera versión donde el comando está disponible en general. El segundo significa que Anthropic ha desactivado el comando del lado del servidor; nada en su máquina lo vuelve a activar.

Qué hacer:

• Ejecute claude --version, luego claude update, y ejecute el comando nuevamente en una sesión nueva. Consulte los requisitos para plugin evals
• Si ve el segundo mensaje en una compilación actual, intente nuevamente más tarde después de otro claude update

Marketplace is registered from an untrusted source

El marketplace está registrado bajo un nombre que está reservado para marketplaces oficiales de Anthropic, pero su fuente registrada no es un repositorio de GitHub de anthropics. Claude Code vuelve a verificar los nombres reservados cada vez que carga o actualiza un marketplace, por lo que el marketplace y los plugins instalados desde él dejan de cargarse. Antes de v2.1.205, una entrada registrada antes de que su nombre se reservara seguía cargándose.

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

Para un marketplace cuya fuente no es un repositorio de GitHub o una URL de Git, como un directorio local, la oración del medio dice can only be used with GitHub sources from the 'anthropics' organization en su lugar. claude plugin marketplace add ejecuta la misma verificación y rechaza un nombre reservado con Failed to add marketplace: seguido de la misma oración de nombre reservado.

Qué hacer:

• Si el marketplace ya está registrado, ejecute claude plugin marketplace remove <name>, luego agréguelo nuevamente desde el repositorio oficial github.com/anthropics
• Si publica un marketplace de terceros que utilizó el nombre antes de que se reservara, cámbielo de nombre y pida a los usuarios que lo vuelvan a agregar desde su fuente
• Consulte la lista de nombres reservados en Marketplace schema

Marketplace name is another spelling of a reserved name

El nombre del marketplace no es en sí mismo un nombre reservado, pero Claude Code lo trata como otra ortografía de uno. Reserved names enumera qué ortografías cuentan como un nombre reservado. Claude Code rechaza tal nombre cuando agrega el marketplace:

Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

Cuando un marketplace ya está registrado bajo tal nombre, su entrada deja de cargarse, y /plugin, claude plugin install, y claude plugin update advierten:

known_marketplaces.json has an entry named "claude.code.plugins", another spelling of the reserved marketplace name "claude-code-plugins", so it is ignored. Remove it with: claude plugin marketplace remove claude.code.plugins

Cuando el nombre requeriría entrecomillado de shell, la negativa en tiempo de adición dice This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be.

Qué hacer:

• Cambie el nombre del marketplace a un nombre que no deletree un nombre reservado y agréguelo nuevamente
• Para la advertencia de entrada ignorada, ejecute el comando claude plugin marketplace remove que proporciona, o elimine la entrada de ~/.claude/plugins/known_marketplaces.json

Claude Code refuses the marketplace name

Un marketplace registrado cuyo nombre suplanta un marketplace oficial de Anthropic según las reglas que esa sección enumera.

Si un marketplace fue registrado bajo tal nombre antes de que la verificación lo bloqueara, el marketplace y los plugins instalados desde él dejan de cargarse, porque Claude Code verifica el nombre cada vez que lee el catálogo del marketplace. Cuando el nombre imita uno oficial, claude plugin list y la pestaña Errors de /plugin informan cada plugin afectado con un mensaje que comienza:

Claude Code refuses the marketplace name "anthropic-plugins-v2"

Para un nombre que imita, el error del marketplace en sí dice Claude Code refuses this marketplace's name: it looks like one of Anthropic's own en su lugar. claude plugin marketplace add rechaza cualquier nombre que suplante con Marketplace name impersonates an official Anthropic/Claude marketplace.

Antes de v2.1.282, claude plugin list y /plugin informaban los plugins de un nombre que imita como fallidos al cargar también, sin nombrar el nombre del marketplace como la causa.

Qué hacer:

• Ejecute claude plugin marketplace remove <name>. Esto también desinstala los plugins instalados desde el marketplace y elimina sus datos guardados
• Para mantener el marketplace en su lugar, espere hasta que su mantenedor lo renombre, luego ejecute claude plugin marketplace update <name>
• Si publica el marketplace, cámbielo de nombre en su marketplace.json; los usuarios luego actualizan el marketplace en lugar de eliminarlo

Marketplace is already added from a different source

Confirmó agregar un marketplace a través de /plugin install <plugin> --marketplace <source>, y el catálogo que Claude Code obtuvo de esa fuente se llama a sí mismo igual que un marketplace que ya agregó desde una fuente diferente. Claude Code mantiene el marketplace existente en lugar de reemplazarlo, y el plugin no se instala.

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

Qué hacer:

• Si el marketplace que ya agregó es el que desea, instale desde él por nombre: /plugin install <plugin>@<name>
• Para cambiar a la nueva fuente, ejecute /plugin marketplace remove <name>, luego reintente la instalación

Plugin command references user\_config in a shell command

Un hook de plugin, monitor, o comando MCP headersHelper hace referencia a una opción de plugin ${user_config.KEY}, y la cadena sustituida se pasaría a un shell. Un valor configurado que contenga $(...), comillas invertidas o ; se ejecutaría como código allí, por lo que Claude Code se niega a iniciar el componente en lugar de sustituir el valor. La verificación se ejecuta en la plantilla de comando, por lo que el error aparece incluso cuando aún no se ha configurado ningún valor. Antes de v2.1.207, el valor se sustituía en el comando del shell.

La redacción depende de qué superficie hizo referencia a la opción. Un hook de forma de shell informa:

Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}

Un monitor informa:

Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.

Un headersHelper de MCP informa:

headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).

Qué hacer:

• Para un hook, agregue una matriz args para que se ejecute en forma exec, donde cada ${user_config.KEY} se convierte en un argumento sin shell en el medio. O elimine la referencia y lea la variable de entorno $CLAUDE_PLUGIN_OPTION_<KEY> dentro del script
• Para un monitor, elimine la referencia y haga que el script del monitor lea el valor de un archivo de configuración
• Para un headersHelper, mueva ${user_config.KEY} al campo headers del servidor, que no se analiza con shell, o lea el valor dentro del script del helper

Plugin archive integrity check failed

La entrada del marketplace del plugin utiliza una fuente archive con un pin sha256, y el resumen del archivo descargado no coincide con el pin. Claude Code rechaza la instalación, por lo que nada cambia en la caché de plugins. La falta de coincidencia tiene tres causas posibles:

• El archivo en la URL cambió después de que el autor calculó el pin
• El autor ingresó el resumen incorrecto en la entrada del marketplace
• La URL sirve un archivo diferente al que el autor fijó

Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

Qué hacer:

• Si publica el plugin, recalcule el resumen del archivo exacto que sirve la URL, por ejemplo con shasum -a 256 my-plugin.zip, o Get-FileHash -Algorithm SHA256 my-plugin.zip en PowerShell, y actualice el sha256 en la entrada del marketplace
• Si instala el plugin, ejecute /plugin marketplace update <name> para actualizar el catálogo en caso de que la entrada se haya corregido, luego reintente la instalación
• Si los resúmenes aún no coinciden después de una actualización, pregunte al propietario del marketplace qué archivo fijaron antes de instalar

Path escapes plugin directory

Un componente de plugin cuya ruta está declarada en el plugin.json del plugin o en su entrada de marketplace, se resuelve fuera del directorio del plugin. Claude Code descarta esa ruta y carga el resto del plugin. El nombre del componente en el mensaje, como commands o hooks, nombra el campo que declaró la ruta.

commands path escapes plugin directory: ./../shared.md

En la salida del comando claude plugin, el mismo error dice Path escapes plugin directory: ./../shared.md (commands).

Claude Code rechaza tanto una ruta que apunta fuera del plugin tal como está escrita, como ../shared-utils, como un enlace simbólico que conduce fuera del plugin y no es uno que las reglas de enlace simbólico del marketplace permitan. Para un enlace simbólico, el mensaje también dice dónde se resuelve la ruta:

commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

En macOS y Linux, Claude Code también rechaza una ruta de componente que contenga una barra invertida en cualquier lugar, incluso cuando la ruta permanece dentro del plugin. Un plugin cuyas rutas de componentes utilizan separadores de estilo Windows se carga en Windows y activa este rechazo en las otras plataformas:

commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

Antes de v2.1.251, Claude Code cargaba una ruta commands declarada en una entrada de marketplace incluso cuando apuntaba fuera del directorio del plugin.

Antes de v2.1.257, la verificación solo miraba la ortografía de la ruta, no dónde conducía un enlace simbólico.

Qué hacer:

• Mueva el archivo referenciado dentro del directorio del plugin y apunte la ruta a él con una ruta relativa ./
• Si la ruta es un enlace simbólico a un archivo fuera del plugin, reemplace el enlace simbólico con una copia del archivo
• Si el mensaje dice que la ruta contiene una barra invertida, escriba la ruta con barras diagonales, por ejemplo ./commands/deploy.md
• Para compartir archivos con otros plugins en el mismo marketplace, vincúlelos con un enlace simbólico dentro del directorio del plugin, siguiendo las reglas de enlace simbólico

Path could not be checked

Claude Code le preguntó al sistema operativo si existe una ruta de plugin y obtuvo un error que no sea "no encontrado", por lo que no carga lo que la ruta nombra. Cuánto del plugin se carga depende de qué ruta falló:

• Una de las ubicaciones de componentes predeterminadas de un plugin, como la carpeta skills/, el archivo monitors/monitors.json, o un SKILL.md en la raíz del plugin: los otros componentes del plugin aún se cargan
• El directorio del plugin en sí: nada de ese plugin se carga

No ve este error para una ruta que no existe en absoluto. En /plugin, el error aparece bajo el plugin y nombra la ruta y el código que devolvió el sistema operativo:

skills path could not be checked: /home/user/my-plugin/skills (ELOOP)

En claude plugin list, el mismo error dice Path not found: /home/user/my-plugin/skills (skills, ELOOP).

Las causas que producen este error incluyen:

• ELOOP: un enlace simbólico en la ruta apunta a sí mismo o forma un bucle
• EIO o ESTALE: la ruta está en un montaje de red que está roto o obsoleto
• EACCES: uno de los directorios por encima de la ruta le niega permiso para atravesarlo

Qué hacer:

• Reemplace un enlace simbólico que apunta a sí mismo con una carpeta real, o elimínelo
• Si la ruta está en un montaje de red, remonte el recurso compartido
• Si el código es EACCES, restaure su permiso de ejecución en los directorios por encima de la ruta
• Ejecute /reload-plugins después de corregir la ruta, o reinicie Claude Code, para cargar el plugin o componente

Antes de v2.1.265, Claude Code trataba una carpeta de componentes predeterminada que no podía verificar como ausente y cargaba el plugin sin ese componente, sin error.

Marketplace entry path does not stay inside the marketplace directory

La entrada de marketplace del plugin declara una ruta de fuente que Claude Code no puede resolver a una ubicación dentro del directorio del marketplace en sí, por lo que el plugin no se instala ni se carga. La negativa cubre:

• Una ruta de entrada que es absoluta, sube fuera del marketplace con .., o está escrita como una ruta de red
• En macOS y Linux, una ruta de entrada que contiene una barra invertida en cualquier lugar después del ./ inicial
• Una entrada en un marketplace obtenido de una fuente remota, como git o una URL, que alcanza su destino a través de un enlace simbólico que se resuelve fuera del directorio del marketplace
• Una entrada relativa en un marketplace agregado desde una URL directa a su marketplace.json: Claude Code descarga solo ese archivo, por lo que no existen archivos de plugin locales para que la ruta nombre. Consulte Plugins with relative paths fail in URL-based marketplaces

claude plugin install informa la negativa así:

Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped, backslash-containing or link-traversing entry, an entry of a fetched marketplace that resolves or opens outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)

Cuando la entrada de un plugin ya instalado falla la misma verificación, claude plugin list muestra el plugin como failed to load con:

Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.

Qué hacer:

• Si mantiene el marketplace, escriba la source de la entrada como una ruta relativa simple con barras diagonales, como ./plugins/my-plugin, y mantenga cualquier enlace simbólico que cruce apuntado dentro del directorio del marketplace
• Si agregó el marketplace desde una URL directa, las entradas relativas no pueden resolverse. Pida al autor del marketplace que use otra fuente de plugin, o agregue el marketplace desde su repositorio de git en su lugar

Failed to load marketplace configuration

Claude Code mantiene los marketplaces de plugins que ha agregado en un archivo de registro en ~/.claude/plugins/known_marketplaces.json. Un comando de plugin que necesita el registro, como claude plugin install, falla con uno de dos mensajes cuando Claude Code no puede usar el archivo:

• Failed to load marketplace configuration: el archivo no es JSON válido, o no se puede leer. Un archivo vacío falla de esta manera también.
• Marketplace configuration file is corrupted: el archivo es JSON válido pero su contenido no coincide con el esquema del registro.

Con un archivo vacío, claude plugin install informa:

✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF

Antes de v2.1.246, claude plugin install no informaba esta falla.

Qué hacer:

• Abra ~/.claude/plugins/known_marketplaces.json y repare el JSON, o corrija las entradas que el mensaje nombra como no coincidentes con el esquema del registro
• Si no puede repararlo, elimine el archivo o reemplace su contenido con {}, luego vuelva a agregar cada marketplace con claude plugin marketplace add <source>. Claude Code vuelve a registrar los marketplaces que su configuración de usuario o administrada declara en extraKnownMarketplaces la próxima vez que lo inicie en una carpeta que haya confiado.

Plugin is required by your organization

Ejecutó claude plugin disable, o utilizó la pestaña Installed de /plugin, para desactivar un plugin sincronizado desde claude.ai que su organización marca como requerido:

Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.

Claude Code no guarda nada y el plugin permanece habilitado.

Cuando intenta desactivar un plugin del que depende un plugin requerido, Claude Code rechaza de la misma manera, con un mensaje que nombra el plugin requerido que lo necesita.

Qué hacer:

• Pida a un administrador de su organización claude.ai que cambie el estado requerido del plugin en claude.ai

Plugin was not uninstalled

Ejecutó claude plugin uninstall, o eligió Uninstall en la pestaña Installed de /plugin, y la desinstalación se detuvo con un mensaje que comienza "<plugin>" was not uninstalled:. Si el texto después de ese dos puntos comienza con installed_plugins.json en lugar de nombrar un archivo de configuración, la causa es contenido en installed_plugins.json que esta versión de Claude Code no puede leer. Para esa forma, consulte installed_plugins.json holds a record this version can't read.

Cuando Claude Code eliminó la entrada del plugin de enabledPlugins y leyó los archivos de configuración de ese ámbito nuevamente, ya sea el plugin seguía activado allí, o un archivo que podría activarlo no se pudo leer o verificar. Eliminar las opciones guardadas del plugin, secretos y datos mientras una entrada de configuración podría activarlo nuevamente los perdería, por lo que la desinstalación se detiene en su lugar: el plugin permanece instalado y nada que guardó se elimina.

✘ Failed to uninstall plugin "formatter": "formatter" was not uninstalled: it is still switched on in /home/user/project/.claude/settings.local.json, although the settings change reported no error. It is still installed. Take it out of "enabledPlugins" in that file yourself, then uninstall it again.

El medio del mensaje nombra el archivo y la causa:

• it is still switched on in <file>, although the settings change reported no error: la escritura de configuración informó éxito pero la entrada aún está allí cuando se lee el archivo nuevamente
• it is still switched on in <file>, and the settings change failed (<error>): el archivo no se pudo guardar, por la razón entre paréntesis
• <file> is there and could not be read: el archivo existe pero no se pudo leer como configuración, por ejemplo porque no es JSON válido, por lo que aún puede activar el plugin
• <file> (not read: it is on a network path or is a link to one, or could not be checked): Claude Code no leyó el archivo de configuración del proyecto o local porque el archivo, o la carpeta .claude que lo contiene, es un enlace que conduce a una ubicación de red, o porque no pudo examinar esa ruta

claude plugin uninstall sale con código 1, y con --json el resultado lleva failureCode: "settings_still_on". /plugin muestra el mismo mensaje.

Qué hacer:

• Siga la última oración del mensaje: repare o reemplace el archivo de configuración que nombra, o elimine la entrada del plugin de enabledPlugins en ese archivo usted mismo, luego ejecute la desinstalación nuevamente

Errores de herramientas

Estos errores provienen de las herramientas integradas de Claude. Claude corrige la mayoría de los errores de herramientas por sí solo. Cuando uno requiere un cambio de su parte, la lista Qué hacer de ese error indica qué cambiar.

Agent would be spawned with zero tools

Cada entrada en la lista tools de la subagente no coincidió con ninguna herramienta utilizable, por lo que Claude Code se negó a lanzar la subagente: sin herramientas, no podía actuar. El mensaje agrupa sus entradas por lo que salió mal:

• Unrecognized: la entrada no coincide con ningún nombre de herramienta, generalmente un error tipográfico como Grpe para Grep.
• Not available to subagents: la entrada nombra una herramienta real que las subagentes no pueden usar. Las subagentes de fondo mantienen un conjunto de herramientas integradas más pequeño, por lo que una entrada que solo una subagente en primer plano puede usar termina aquí cuando la subagente se ejecutaría en segundo plano, que es lo predeterminado. Si enumera Agent, el mensaje lo reporta bajo el siguiente grupo en su lugar.
• Matched no tools in this session: la entrada es válida pero ninguna herramienta en la sesión actual coincide con ella en este momento, como mcp__github__* sin servidor MCP de GitHub conectado, o Agent para una subagente en el límite de profundidad.

Omitir el campo tools nunca activa este rechazo. Si deja la lista tools vacía, o disallowedTools elimina cada entrada en ella, Claude Code también omite el rechazo y lanza la subagente sin herramientas.

Antes de v2.1.208, la subagente se lanzaba sin herramientas y podía devolver un resultado vacío o confuso.

Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

Qué hacer:

• Corrija cada entrada que el error nombra contra las herramientas disponibles para subagentes
• Elimine entradas para herramientas que la sesión no tiene, como herramientas MCP de un servidor que no está conectado
• Para una herramienta que las subagentes de fondo descartan, como CronCreate, elimine la entrada. Para mantener la herramienta, desactive el modo fork y pida a Claude que ejecute la subagente en primer plano
• Elimine el campo tools en lugar de enumerar herramientas para dar a la subagente cada herramienta disponible para subagentes
• Para una lista tools que contiene solo Agent, aumente el límite de profundidad o dé al agente al menos otra herramienta: Claude Code retiene Agent en ese límite, por lo que una lista sin nada más en ella se resuelve a ninguna herramienta

File is covered by a Read deny rule

La herramienta Edit o Write fue llamada en una ruta coincidida por una regla de denegación Read, incluyendo la creación de un nuevo archivo en esa ruta. Ambas herramientas cambian contenido que Claude debe poder leer de nuevo, por lo que Claude Code se niega a la llamada antes de cualquier acceso a archivos. NotebookEdit no está cubierto por reglas de denegación Read. Antes de v2.1.228, la regla bloqueaba solo la herramienta Edit, y antes de v2.1.208, solo una regla de denegación Edit bloqueaba ediciones.

File is covered by a Read deny rule in your permission settings and cannot be edited.

Cuando Claude Code se niega a la herramienta Write, el mensaje termina con and cannot be written en su lugar.

Qué hacer:

• Si Claude debe poder cambiar el archivo, elimine o reduzca la regla de denegación Read en /permissions o en configuración
• Si el archivo debe permanecer intacto, mantenga la regla y agregue una regla de denegación Edit para la misma ruta para bloquear también la herramienta NotebookEdit

Path cannot contain null bytes

Una llamada de herramienta de archivo con argumento de ruta o patrón contenía un byte nulo, que los sistemas de archivos y herramientas de búsqueda no pueden aceptar. Read, Write, Edit, NotebookEdit, Glob, y Grep verifican esto, y el mensaje nombra la herramienta y el argumento:

Read file_path cannot contain null bytes (\0). Remove the null byte and try again.

La llamada de herramienta falla, Claude ve el error, y el turno continúa.

Qué hacer:

• Nada de su parte: el error se devuelve a Claude como el resultado de la herramienta, y el mensaje en sí le dice a Claude que elimine el byte nulo e intente de nuevo

Antes de v2.1.281, un byte nulo en una ruta Read, Write, Edit, o NotebookEdit terminaba todo el turno con un error que nombraba Path contains null bytes, y la herramienta nunca se ejecutaba.

subagent\_type is required

subagent_type is required: the general-purpose agent is not available in this session. Available agents: ...

Claude llamó a la herramienta Agent sin un subagent_type, y esta sesión no tiene subagente de propósito general como alternativa. Ese es el caso en dos configuraciones:

• CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 está configurado en modo no interactivo, que elimina cada subagente integrada
• El agente de hilo principal de la sesión tiene una lista de permisos tools: Agent(...) que deja fuera general-purpose

Qué hacer:

• Generalmente nada: el mensaje enumera las subagentes que la sesión sí tiene, por lo que Claude puede reintentar con una de ellas
• Si Claude sigue fallando, agregue general-purpose a la lista de permisos tools: Agent(...), o desactive CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS

Antes de v2.1.235, la misma llamada fallaba con Agent type 'general-purpose' not found.

Memory index is over its read limit

Claude escribió en el índice de memoria automática MEMORY.md y lo dejó por encima de uno de sus límites de lectura: 200 líneas o 25KB. La escritura fue exitosa, pero solo las primeras 200 líneas o 25KB, lo que sea menor, se cargan al inicio de una sesión, por lo que todo lo que está más allá del límite se descarta cada vez que se lee el índice. Antes de v2.1.210, un índice que excedía el límite se truncaba silenciosamente en la siguiente carga sin señal de escritura.

Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.

Solo el contenido que se carga cuenta hacia los límites. El frontmatter YAML y los comentarios HTML a nivel de bloque se eliminan antes de que se cargue el índice, por lo que se excluyen de la medición. Antes de v2.1.211, Claude Code medía el archivo sin procesar, y el frontmatter o los comentarios podrían activar este error incluso cuando el contenido cargado se ajustaba.

Claude Code entrega el error a Claude después de la escritura en lugar de imprimirlo como un banner en su terminal, por lo que puede notarlo solo en la transcripción.

Cuando la escritura de Claude acerca el archivo a un límite sin cruzarlo, Claude Code devuelve un recordatorio más suave para compactar el índice en lugar de este error.

Qué hacer:

• Permita que Claude reescriba MEMORY.md, o pídale que lo haga: mantenga una línea por entrada, mueva los detalles a archivos de tema y fusione o descarte entradas obsoletas
• Para recortar el índice usted mismo, consulte Auditar y editar su memoria

pkill pattern matches the Claude Code process

Un comando pkill en una llamada de herramienta Bash usó un patrón, típicamente con -f, que coincide con el proceso Claude Code en sí, por lo que Claude Code se niega al comando en lugar de permitir que termine la sesión. Claude Code prueba el patrón con pgrep antes de ejecutar pkill y se niega cuando su propio ID de proceso está en el resultado. La verificación se ejecuta solo en Linux; en macOS, pkill se ejecuta sin modificaciones. Antes de v2.1.214, el comando se ejecutaba, y un patrón coincidente mataba la sesión Claude Code a mitad de turno.

pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.

El rechazo aparece en el resultado de la herramienta Bash en lugar de como un banner en su terminal, y Claude generalmente ajusta el comando por sí solo.

Qué hacer:

• Reduzca el patrón para que coincida solo con el proceso previsto, por ejemplo la ruta completa del binario de destino en lugar de una subcadena corta
• Para detener procesos iniciados por el shell actual, use pkill -P $$ con el patrón, que limita la coincidencia a los procesos secundarios del shell

Failed to write to a teammate's inbox

Claude Code no pudo escribir un mensaje en el archivo de buzón de un compañero de equipo bajo ~/.claude/teams/{team-name}/inboxes/, por lo que el destinatario no recibió nada. La escritura falla cuando Claude Code no puede crear o actualizar el archivo, por ejemplo porque el disco está lleno, el directorio no es escribible, o otro agente mantiene el bloqueo del buzón durante demasiado tiempo. Antes de v2.1.224, Claude Code reportaba el mensaje como enviado incluso cuando la escritura fallaba.

El error aparece en el resultado de la herramienta del agente remitente en lugar de como un banner en su terminal, y su texto le dice a Claude que intente de nuevo:

Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.

Los mensajes de protocolo de equipo de agentes estructurados fallan de la misma manera, y el error nombra el mensaje no entregado: cuando Claude Code no puede escribir una aprobación de plan, rechazo de plan, solicitud de apagado o rechazo de apagado, el error dice Failed to write the <message> to <name>'s inbox — nothing was sent. La plan approval en esa lista es la decisión del líder aprobando el plan de un compañero; el envío del plan del compañero es el mensaje separado plan approval request. Ese mensaje y otros dos mensajes de protocolo llevan su propio texto de mensaje y consecuencia:

• Failed to write the plan approval request to the lead's inbox — plan not submitted; try again: el plan del compañero nunca llegó al líder, y el compañero permanece en modo de plan hasta que un reenvío sea exitoso
• The permission request could not be delivered to the team lead (mailbox write failed): la solicitud de permiso del compañero nunca llegó al líder, por lo que nadie aprobó la llamada de herramienta
• The confirmation could not be written to team-lead's inbox.: la aprobación del apagado en sí tuvo efecto y el compañero sale; solo falta la confirmación al líder

Cuando usted mismo envía un mensaje a un compañero, escribiendo @name seguido del mensaje en la sesión del líder, la misma falla aparece como una notificación, Couldn't write to @name's inbox — message not sent. Try again., y Claude Code mantiene su texto en el cuadro de solicitud para que pueda enviarlo de nuevo.

Qué hacer:

• Pida al remitente que reenvíe el mensaje; la contención por el bloqueo del buzón es transitoria y se resuelve al reintentar
• Verifique el espacio en disco libre y compruebe que ~/.claude/teams y los archivos bajo él sean escribibles por su usuario

Teammate's agent definition was not restored

Claude envió un mensaje a un compañero de equipo de agentes detenido, y Claude Code lo reactivó sin volver a aplicar la definición de subagente desde la que fue generado, porque su archivo de definición provenía de una carpeta sin confianza guardada. El aviso sigue el informe de reanudación en el resultado de la herramienta del agente remitente:

Its agent definition was not restored: the folder its definition file came from is not trusted (source: projectSettings), so the teammate is running with the team-essential tools and no custom instructions. To restore it, the user needs to run Claude Code in that folder once and accept the trust dialog (the --debug log names the folder); do not change trust settings on the user's behalf.

La verificación se aplica a una definición en el directorio .claude/agents/ del proyecto o de un directorio --add-dir, y aceptar el diálogo de confianza para una carpeta principal no lo satisface.

Qué hacer:

• Ejecute claude en la carpeta que el registro de depuración nombra y acepte el diálogo de confianza. La definición se vuelve a aplicar la próxima vez que Claude Code reactivar el compañero; no necesita reiniciar la sesión del líder
• O configure la entrada hasTrustDialogAccepted a true en ~/.claude.json, usando la clave exacta projects["<path>"] que el registro de depuración imprime

Message too large for cross-session delivery

El mensaje entre sesiones de Claude a otra de sus sesiones en esta máquina era demasiado largo para enviar. Claude Code se negó, y la sesión receptora no recibió nada. El rechazo aparece en el resultado de la herramienta de la sesión remitente, no como un banner en su terminal. Nombra ambos tamaños y cómo hacer que el mensaje se ajuste:

Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.

Reenviar el mismo texto falla de la misma manera.

Qué hacer:

• Pida a Claude que resuma el mensaje, o que ponga el contenido voluminoso en un archivo y envíe la ruta del archivo
• Pida a Claude que divida el contenido en varios mensajes más cortos

Antes de v2.1.235, Claude Code reportaba un mensaje de tamaño excesivo como enviado. La sesión receptora lo descartaba sin leer.

Too many messages to this session just now

Claude envió una ráfaga rápida de mensajes entre sesiones a una de sus sesiones en esta máquina, y la ráfaga alcanzó lo que esa sesión de bandeja de entrada acepta. Claude Code se negó al siguiente envío, y la sesión receptora no recibió nada de él. El rechazo aparece en el resultado de la herramienta de la sesión remitente, no como un banner en su terminal:

Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.

Qué hacer:

• Generalmente nada: Claude agrupa el contenido restante en un mensaje, o espera antes de enviar más
• Si usted mismo solicitó la ráfaga, pida a Claude que combine lo que queda en un único mensaje

Antes de v2.1.236, Claude Code reportaba estos envíos como enviados. La sesión receptora los descartaba sin leer.

Cross-session message was dropped at the recipient session's inbox

Claude envió un mensaje entre sesiones a otra de sus sesiones en esta máquina, y la bandeja de entrada de esa sesión lo descartó antes de que Claude en esa sesión lo leyera. La línea nombra la dirección del destinatario y, cuando el destinatario dio una razón, agrega la razón después de un guión:

Cross-session message was dropped at the recipient session's inbox (recipient: uds:/tmp/cc-socks/13605.sock) and not delivered — its queue of undelivered peer messages was full. Claude was told not to resend right away.

Una línea puede cubrir varios mensajes descartados. Luego comienza en plural, por ejemplo Cross-session messages (12) were dropped. Para encontrar a qué sesión pertenece una dirección, compárela con la fila Peer address que /status muestra en cada sesión.

Después del guión, la línea da una o más de estas razones:

• its queue of undelivered peer messages was full: el destinatario ya tenía tantos mensajes no entregados de otras sesiones como su cola permite
• you sent faster than that session accepts: los mensajes de la sesión remitente llegaron más rápido de lo que el destinatario acepta de un remitente
• it repeated your previous message: el mensaje era idéntico a uno que la sesión remitente envió a este destinatario poco antes
• a relay loop between sessions was cut: el mensaje continuaba una cadena de sesiones enviándose mensajes entre sí, y la cadena había pasado por el destinatario demasiadas veces o se había vuelto demasiado larga

Qué hacer:

• Asuma que el destinatario nunca vio los mensajes descartados. Claude Code le dice lo mismo, y le dice que incluya cualquier cosa que aún importe en un mensaje posterior en su lugar de reenviar de inmediato
• Si sus sesiones se envían actualizaciones frecuentes entre sí, pida a Claude que envíe menos mensajes más grandes, como un informe cuando una sesión termina su trabajo
• Para a relay loop between sessions was cut, escriba la siguiente instrucción en una de las sesiones usted mismo. Un mensaje que Claude envía en respuesta a su propio mensaje comienza una nueva cadena

Antes de v2.1.238, la sesión remitente no recibía ningún informe cuando la bandeja de entrada del destinatario descartaba un mensaje.

Refusing to send a cross-session message

Antes de que Claude Code escriba un mensaje entre sesiones a otra de sus sesiones en esta máquina, verifica que el socket de bandeja de entrada de la sesión de destino sea el punto final al que se dirigió el mensaje. Cuando una verificación falla, Claude Code se niega al envío en la sesión remitente, y la sesión de destino no recibe nada. Para un mensaje que Claude envía, el rechazo aparece en el resultado de la herramienta de la sesión remitente:

Failed to send to api-worker: Refusing to send: reply target is a symlink

El texto después de Refusing to send: nombra la verificación que falló:

• reply target is a symlink: un enlace simbólico se encuentra en la ruta del socket de la sesión de destino. Claude Code no entrega a través de él, porque un enlace allí podría redirigir el mensaje a un punto final que la sesión de destino no creó.
• cannot vet reply target: Claude Code no pudo inspeccionar la ruta de destino en absoluto, por ejemplo porque leerla falló con un error de permiso.

Qué hacer:

• Generalmente nada: las verificaciones evitan que un mensaje llegue a un punto final que no sea la sesión a la que se dirigió, y nada fue enviado
• Si reply target is a symlink se repite para una sesión, verifique qué creó un enlace en la ruta del socket de esa sesión, que se muestra en su /status bajo Peer address

Refusing to read, write, or search a path

Claude Code verifica las reglas de permiso de una ruta de archivo, luego confirma esa resolución nuevamente cuando la herramienta abre el archivo o inicia la búsqueda. Cuando no puede confirmar que la ruta aún conduce a la ubicación que la verificación aprobó, Claude Code se niega a la operación en lugar de seguirla. El rechazo aparece en el resultado de la herramienta:

Refusing to read /path/to/file: its symlink resolution changed after permission was checked (a link on the way now leads somewhere the check did not see). If a link in the working directory is being rewritten concurrently, stop that and retry.

Cada rechazo nombra su razón:

• its symlink resolution changed after permission was checked: un enlace simbólico a lo largo de la ruta, o en una raíz de búsqueda Grep o Glob, fue reemplazado entre la verificación de permiso y la operación. En un rechazo de lectura, la frase entre paréntesis nombra qué comparación falló.
• its parent-directory symlink resolution changed after permission was checked: un directorio por el que pasa la ruta de escritura ya no se resuelve a la ubicación aprobada
• where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve): Claude Code no pudo seguir la ruta a una ubicación final en el disco, por ejemplo porque los enlaces simbólicos en ella forman un bucle
• it is a symbolic link. Write to the link's target path instead: un enlace simbólico se encuentra en la ubicación de escritura aprobada en sí, por ejemplo un CLAUDE.md que es un enlace simbólico a AGENTS.md; el mensaje dirige a Claude a la ruta de destino del enlace
• Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.: la misma condición detectada cuando otro escritor abre el archivo, como una escritura a un .mcp.json enlazado simbólicamente
• Refusing to write into symlinked directory: <path>: el directorio que contiene el archivo es en sí mismo un enlace simbólico, por ejemplo el directorio .claude/ de un proyecto vinculado a otra ubicación
• a path one of its Read deny rules is written through changed while the search was being prepared. Retry.: una regla de denegación Read para la búsqueda nombra una ruta que pasa a través de un enlace simbólico, y ese enlace cambió mientras Claude Code estaba preparando la búsqueda
• it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.: la raíz de búsqueda existe pero no pudo abrirse; el código entre paréntesis es el error del sistema operativo
• its permission check expired before it ran (too many concurrent file operations). Retry.: Claude Code desalojó el registro de aprobación bajo muchas operaciones de archivo simultáneas antes de que la herramienta lo usara; reintentar ejecuta una verificación de permiso nueva
• ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration: Claude Code no pudo resolver el binario rg a una ruta absoluta, por lo que se niega a búsquedas fuera del directorio de trabajo en lugar de ejecutar una que sus reglas de denegación no cubran

Qué hacer:

• Generalmente nada: el rechazo llega a Claude como el resultado de la herramienta, y la operación rechazada no se ejecuta
• Si un rechazo de enlace simbólico se repite en una ruta, encuentre qué sigue reescribiendo un enlace allí, como una herramienta de compilación o un observador de archivos, o pida a Claude que use la ruta resuelta del archivo en lugar de la vinculada
• Si este rechazo aparece para cada archivo mientras Claude Code se ejecuta en Windows dentro de un AppContainer o sandbox de token restringido, actualice a v2.1.265 o posterior
• Si un rechazo de lectura aparece en macOS para un archivo que nada está reescribiendo, como una captura de pantalla arrastrada al mensaje, actualice a v2.1.273 o posterior
• Para el rechazo de ripgrep, instale ripgrep con su administrador de paquetes para que rg se resuelva a una ruta absoluta en PATH, o mantenga búsquedas bajo el directorio de trabajo

Antes de v2.1.251, Claude Code volvía a verificar la resolución de una ruta solo para escrituras de archivo, por lo que un enlace reemplazado después de la verificación de permiso podría redirigir una lectura o búsqueda a una ubicación diferente sin un mensaje. De estos rechazos, solo el rechazo de escritura del directorio principal, a través de enlace simbólico y directorio enlazado simbólicamente aparecen en versiones anteriores.

Antes de v2.1.280, el rechazo where it leads on disk could not be determined no aparecía.

Task output swap refused

Claude Code guarda la salida de cada comando Bash en un archivo bajo su directorio temporal. Cada vez que abre uno de estos archivos, verifica que la ruta aún conduce al archivo que creó, sin enlace simbólico, enlace duro adicional o directorio movido redirigiendo. Este mensaje significa que esa verificación falló, por lo que Claude Code se negó a la operación en lugar de escribir o leer salida a través de esa ruta. El mensaje aparece en el resultado de la herramienta Bash:

task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.

El texto entre paréntesis nombra la verificación que falló. Razones como output symlink was re-pointed, output file identity changed, y not a regular file todas reportan la misma condición: algo en o a lo largo de la ruta de salida ya no es el archivo que Claude Code creó. Solo algunas razones llevan una oración To recover:.

Si la verificación falla mientras un comando aún se está ejecutando, Claude Code detiene el comando, y su resultado reporta:

Command killed: its output file was replaced or could no longer be verified

Qué hacer:

• Actualice a v2.1.260 o posterior. Las versiones anteriores a veces mostraban este mensaje cuando no había enlace o directorio movido presente
• Reinicie Claude Code con CLAUDE_CODE_TMPDIR configurado en un directorio nuevo
• O verifique el directorio de su proyecto bajo el directorio temporal de Claude Code, /private/tmp/claude-501/-Users-you-my-project en el mensaje de ejemplo. Si esa ruta es un enlace simbólico, o un directorio que no debería estar allí, elimine el enlace o directorio en sí en lugar del destino del enlace, y reinicie Claude Code
• Si el rechazo se repite, un proceso está reemplazando, vinculando o eliminando entradas bajo el directorio temporal de Claude Code mientras la sesión se ejecuta. Configure CLAUDE_CODE_TMPDIR en un directorio que nada más administre y reinicie

Disk quota or temp filesystem is full

Claude Code guarda la salida de cada comando Bash y PowerShell en un archivo bajo su directorio temporal. Cuando un comando sale con un código distinto de cero y sin salida en absoluto, Claude Code verifica si el sistema de archivos que contiene ese archivo se quedó sin espacio o inodos, o si su cuota de disco en él está agotada. Si es así, un diagnóstico aparece en el resultado del comando en lugar de la salida vacía:

Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.

El mensaje nombra lo que se agotó:

• Your disk quota is full ... (EDQUOT): su propia cuota en ese sistema de archivos está agotada. Una cuota puede estar llena mientras el sistema de archivos aún muestra espacio libre
• The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC): el sistema de archivos, o su cuota en él, no tiene espacio restante
• Command output was lost: the temp filesystem at ... is full o ... is out of inodes: el sistema de archivos tiene casi ningún espacio libre restante, o se está quedando sin inodos

Qué hacer:

• Elimine archivos que ya no necesita en el sistema de archivos que contiene el directorio temporal de Claude Code. Para EDQUOT, elimine archivos que cuenten contra su propia cuota. Para out of inodes, elimine muchos archivos en lugar de unos pocos grandes, ya que cada archivo toma un inodo sin importar su tamaño
• O reinicie Claude Code con CLAUDE_CODE_TMPDIR configurado en un directorio en un sistema de archivos con espacio
• Luego pida a Claude que ejecute el comando de nuevo. La salida que imprimió se perdió, no se truncó

The source file is not valid UTF-8 text

Claude intentó publicar un artefacto desde un archivo cuyos bytes no se decodifican como texto, o cuyo texto ya contiene el carácter de reemplazo U+FFFD, por lo que Claude Code se negó a publicar antes de cargar nada. El mensaje aparece en el resultado de la herramienta Artifact y nombra la primera posición a corregir:

file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.

file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.

Claude Code decodifica el archivo como UTF-8, o como UTF-16 cuando comienza con una marca de orden de bytes UTF-16 little-endian. Cuando tal archivo UTF-16 no se decodifica, el primer mensaje nombra UTF-16 y aún le dice que reescriba el archivo como UTF-8. Cuando más posiciones siguen la nombrada, el mensaje agrega un conteo como (+2 more) después de la posición.

Qué hacer:

• Generalmente nada: Claude reescribe el archivo y publica de nuevo
• Si el archivo es uno que escribió o exportó, guárdelo de nuevo como UTF-8, y reemplace cada U+FFFD con el carácter que una edición, pegado o conversión anterior perdió
• Para mostrar un U+FFFD intencional en la página, escríbalo como � en el HTML en lugar del carácter literal

Antes de v2.1.267, Claude Code cargaba tal archivo sin verificarlo, y el servidor se negaba a publicar en su lugar.

Reading a local file from outside the connected folders in a Cowork session

En una sesión de Cowork ejecutándose en su máquina en la aplicación Claude Desktop, Claude nombró un archivo local para un artefacto. Claude Code no pudo confirmar que el archivo es un archivo simple dentro de las carpetas conectadas de la sesión: la ruta se encuentra fuera de esas carpetas, pasa a través de un enlace simbólico, o está escrita de una manera que puede nombrar un archivo diferente al que parece. Leer tal archivo necesita su aprobación, y en una sesión que no puede mostrarle la tarjeta de aprobación, como una configurada para omitir todas las aprobaciones, Claude Code se niega a la lectura.

El rechazo aparece en el resultado de la herramienta Artifact; cuando el archivo no pudo ser examinado en absoluto, nombra esa falla en su lugar:

Reading a local file from outside this session's connected folders, or through a link, needs the approval card, and no one can answer it in this Cowork session. Use a plain file inside the connected folders; do not retry this file in this session.

cannot read file_path (ENOENT) — the file could not be examined, and no one can answer the approval card in this Cowork session. Check that the file exists as a plain file inside the connected folders, then retry with that path.

Qué hacer:

• Generalmente nada: el mensaje le dice a Claude que use un archivo simple dentro de las carpetas conectadas en su lugar
• Para poner ese archivo exacto en el artefacto, cópielo en una de las carpetas conectadas de la sesión como un archivo regular, no un enlace simbólico, y pregunte de nuevo

WebFetch cannot fetch localhost

Claude llamó a WebFetch con una URL cuyo nombre de host no tiene punto, como http://localhost:3000 o un nombre de intranet simple como http://wiki/. WebFetch se niega a estas URL antes de hacer cualquier solicitud:

WebFetch cannot fetch localhost or other hostnames without a dot. To reach a local server, use Bash with curl instead.

Qué hacer:

• Generalmente nada: el mensaje señala a Claude hacia curl a través de la herramienta Bash, que puede alcanzar servidores locales e intranet

Antes de v2.1.268, WebFetch reportaba estas URL con un error genérico Invalid URL.

WebFetch domain safety check failed

Antes de obtener una URL, WebFetch envía el nombre de host de la URL a api.anthropic.com para verificarlo contra la lista de bloqueo de seguridad de dominio de Anthropic. Si la verificación no se puede completar, WebFetch no puede confirmar que el dominio es seguro, por lo que no obtiene la página y el resultado de la herramienta lleva uno de estos mensajes en su lugar:

The safety check for domain example.com is rate-limited (too many domain checks from this network; the limit is shared and can stay exhausted for minutes). Do not retry WebFetch in a loop or sleep to wait it out; continue without this page and report that its safety check was rate-limited. A single later attempt is fine; if that is rate-limited too, stop.

Unable to verify if domain example.com is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.

• rate-limited: el punto final de verificación respondió con HTTP 429. El mensaje le dice a Claude que continúe sin la página e intente de nuevo como máximo una vez más tarde. Claude Code no almacena en caché una verificación fallida, por lo que una obtención posterior de ese dominio ejecuta la verificación de nuevo. Si las sesiones en su red alcanzan esto a menudo, puede omitir la verificación con skipWebFetchPreflight: true en configuración.
• Unable to verify: la solicitud de verificación falló, agotó el tiempo de espera, u obtuvo otro estado de error. Si su red bloquea api.anthropic.com, agregue ese dominio a la lista de permitidos, u omita la verificación con skipWebFetchPreflight: true en configuración.

Antes de v2.1.286, el mensaje de límite de velocidad decía The safety check for domain example.com is temporarily rate-limited (too many domain checks from this network). Retry after about a minute; retrying sooner will fail the same way.. Antes de v2.1.285, una verificación con límite de velocidad se reportaba con el mensaje Unable to verify en su lugar.

Errores de sesión en segundo plano

Las sesiones en segundo plano se ejecutan sin su propia terminal interactiva, por lo que los comandos que necesitan una se comportan de manera diferente allí. Estos mensajes aparecen en la transcripción de una sesión en segundo plano, en la terminal que se conecta a una, en la sesión o shell desde la que haces el envío, o, para las entradas de protección de worktree a continuación, en cualquier sesión aislada en un worktree o que ejecute un subagente aislado en worktree; cuando un mensaje es específico de una superficie, su entrada lo indica.

Comandos rechazados en una sesión en segundo plano

Los comandos que abren un diálogo interactivo no pueden hacerlo mientras no hay terminal conectada a una sesión en segundo plano. /install-github-app, la lista de configuración /mcp y las acciones de autenticación en el menú del servidor MCP responden con un mensaje. Para /install-github-app y la lista de configuración /mcp, la sesión también aparece bajo Needs input en agent view para que puedas encontrarla, conectarte y ejecutar el comando nuevamente. Mientras una terminal está conectada, estos comandos funcionan normalmente.

Antes de v2.1.216, la sesión no aparecía bajo Needs input después de que /install-github-app o la lista de configuración /mcp se rechazara. En v2.1.213 a v2.1.215, los comandos seguían funcionando mientras una terminal estaba conectada, y el mensaje de rechazo te indicaba que te conectaras y ejecutaras el comando nuevamente. De v2.1.208 a v2.1.212, Claude Code los rechazaba incluso mientras una terminal estaba conectada, con un mensaje como Can't open MCP settings in a background session; en esas versiones, ejecuta el comando desde una sesión claude normal en su lugar, o actualiza. Antes de v2.1.208, abrían su diálogo dentro de la sesión en segundo plano. Solo en v2.1.208, Claude Code también rechazaba el selector /model en una sesión en segundo plano, y /upgrade imprimía la URL de actualización en lugar de abrir un navegador.

La redacción nombra el comando. La lista de configuración /mcp reporta:

Can't open MCP settings while no terminal is attached to this background session. This session now shows "needs input" in agent view — open it and run /mcp to manage servers, or use `/mcp enable|disable|reconnect <server>` to steer without the panel.

Qué hacer:

• Conéctate a la sesión desde agent view y ejecuta el comando nuevamente
• O usa la forma que el mensaje nombra, como /mcp reconnect <server>, /mcp enable o /mcp disable, que funcionan sin conectarse

Escritura o comando bloqueado porque la ruta no se puede resolver de forma segura

Claude se refirió a un archivo o directorio de trabajo mediante una escritura de ruta que el protector de aislamiento de worktree no puede resolver a una única ubicación verificable. El protector verifica escrituras y directorios de trabajo de comandos en cualquier sesión aislada en un worktree, interactiva o en segundo plano, y en subagentes aislados en worktree. Resuelve enlaces simbólicos antes de verificar que la operación no llegue al checkout compartido, y cuando la resolución falla, bloquea la operación en lugar de permitir que llegue allí. El mensaje nombra las formas de ruta que rechaza y cómo reintentar:

This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.

Un comando bloqueado reporta la misma causa para su directorio de trabajo y termina con re-run the command from its direct symlink-free path. Antes de v2.1.217, el protector comparaba las escrituras de ruta sin resolver enlaces simbólicos, por lo que estas escrituras no se bloqueaban y una escritura enrutada a través de un enlace simbólico podía llegar al checkout compartido.

Qué hacer:

• Generalmente nada: el mensaje completo va a Claude como un error de herramienta, y Claude reintenta con la ruta directa que nombra. Para una edición de archivo bloqueada, la vista de conversación muestra solo una línea corta Error editing file; el mensaje completo aparece en la vista de transcripción, que abres con Ctrl+O. Un comando bloqueado lo imprime en su salida.
• Si el bloqueo se repite en el mismo archivo, la ruta probablemente pasa por un enlace simbólico incluido en un commit cuyo destino contiene .., como docs/current -> ../README.md; pide a Claude que edite el archivo de destino por su ruta real en lugar de a través del enlace

Escritura o comando bloqueado porque la ruta nombra una ubicación de red

Claude se refirió a un archivo o directorio de trabajo mediante una ruta que nombra una unidad que no está en tu máquina, un recurso compartido UNC como \\server\share\file o una ruta de automontaje /net, mientras que el checkout de la sesión está en un disco local. El mismo protector de aislamiento de worktree no puede verificar que tal ruta se mantenga fuera del checkout compartido, por lo que bloquea la operación. Aislar la sesión en un worktree no levanta el bloqueo. El mensaje nombra la forma de ruta a usar en su lugar:

This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.

Un comando bloqueado reporta la misma causa para su directorio de trabajo y termina con re-run the command from its local, plainly-spelled path. Antes de v2.1.217, el protector comparaba solo el texto de la ruta, por lo que referirse a un archivo dentro del checkout mediante una ruta UNC o /net no se bloqueaba.

Qué hacer:

• Generalmente nada: Claude reintenta con la escritura local que el mensaje solicita

Comando bloqueado por las verificaciones de aislamiento de worktree

Claude ejecutó un comando Bash o Monitor en una sesión aislada en un worktree, y Claude Code lo rechazó por una de dos razones:

• El comando apunta git al checkout principal.
• Claude Code no puede verificar a partir del texto del comando que cualquier git que ejecute el comando se mantenga dentro del worktree. Un comando que nunca nombra git aún puede ser rechazado por esta razón, porque expandir una indirección de variable como ${!name} o ejecutar una sustitución de función Bash como ${ command; } produce un valor en tiempo de ejecución que en sí mismo puede ser un comando.

La parte central del mensaje nombra lo que no se pudo verificar:

This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.

Qué hacer:

• Generalmente nada: Claude lee el mensaje y reescribe el comando de la manera que su oración final solicita
• Si un comando que pediste sigue siendo rechazado, escribe el valor marcado literalmente: reemplaza la indirección o sustitución con su valor, y ejecuta git como su propio comando simple desde dentro del worktree
• Para actuar en el checkout principal a propósito, ejecuta el comando tú mismo en una terminal fuera de la sesión

Esta sesión no tiene transcripción guardada

Te conectaste a una sesión en segundo plano detenida que fue enviada a segundo plano desde otra conversación con ← o /background y se detuvo antes de que su primera respuesta terminara. Hasta que esa primera respuesta termine, la conversación aún vive solo en la sesión desde la que fue enviada a segundo plano, por lo que claude attach se niega a iniciar la sesión detenida en lugar de comenzar una conversación en blanco bajo el mismo ID de sesión. El mensaje termina con el comando claude respawn para esta sesión:

This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

Abrir la fila de la misma sesión en agent view muestra Press enter again to restart this session fresh debajo de la lista en su lugar, y un segundo Enter en la fila reinicia la sesión con una conversación vacía. Antes de v2.1.212, abrir la fila mostraba el mensaje de rechazo sin forma de reiniciar desde agent view. Antes de v2.1.211, abrir la sesión detenida iniciaba silenciosamente esa conversación en blanco y podía volver a ejecutar el prompt original de la sesión.

Qué hacer:

• La conversación desde la que enviaste a segundo plano está intacta: reanúdala con claude --resume o sigue trabajando en ella
• Para iniciar la sesión detenida desde cero de todas formas, ejecuta claude respawn <id> con el ID del mensaje, o presiona Enter dos veces en su fila en agent view
• Si la sesión sí terminó una respuesta y aún ves este rechazo en una versión anterior a v2.1.214, una carpeta ilegible en ~/.claude/projects podía hacer que el escaneo de transcripciones no encontrara la conversación guardada; actualiza a v2.1.214 o posterior, que tolera carpetas ilegibles durante el escaneo

Esta sesión se está ejecutando en otra terminal

Abriste la fila de una sesión detenida en agent view, y su conversación guardada ya está abierta en otro proceso activo de Claude Code en esta máquina, por lo que Claude Code se niega a iniciar un segundo proceso que escribiría en la misma transcripción. El mensaje que ves depende de qué mantiene la conversación:

Can't open — this session is running in another terminal
This conversation is already open in another running Claude session — use that one, or close it and try again

• running in another terminal: una terminal mantiene la conversación, por ejemplo una donde la reanudaste con claude --resume o /resume. La fila también muestra Open in a terminal.
• already open in another running Claude session: otro proceso no interactivo de Claude Code la mantiene, por ejemplo un proceso de sesión en segundo plano para la misma conversación que aún no ha salido.

Claude Code guarda una respuesta que escribiste al abrir la fila y la envía como el siguiente prompt de la sesión la próxima vez que la sesión se inicie.

Qué hacer:

• Continúa la conversación en el proceso que la tiene abierta, o sal de ese proceso y abre la fila nuevamente

Antes de v2.1.248, solo existía el rechazo already open in another running Claude session: una conversación reanudada en una terminal no contaba como abierta, y abrir la fila iniciaba un segundo proceso de Claude Code que escribía en la misma conversación.

La conversación guardada de esta sesión ya no está en el disco

Abriste una sesión en segundo plano que terminó mientras el servicio en segundo plano estaba apagado, y la limpieza de transcripciones ha eliminado desde entonces su conversación guardada, por ejemplo después de que la máquina estuvo apagada durante semanas. Abrir una fila así normalmente reanuda su conversación guardada. Sin nada que reanudar, Claude Code se niega en lugar de volver a ejecutar el prompt original de la sesión sin preguntar:

This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

claude attach <id> imprime este texto. En agent view, el pie de página es más corto y termina con ctrl+x deletes the row.

Qué hacer:

• Ejecuta claude rm <id> para eliminar la fila. Cuando se aplica uno de los casos conservados, claude rm conserva la fila y el worktree en su lugar e indica la razón
• Para ejecutar el prompt original de la sesión nuevamente como una conversación nueva, ejecuta claude respawn <id>

Antes de v2.1.248, abrir una fila así volvía a ejecutar el prompt original de la sesión en lugar de rechazarlo, trayendo de vuelta al primer plano una tarea de hace semanas.

El worktree tiene commits que no se han enviado a ningún lugar

Intentaste eliminar una sesión en segundo plano cuyo worktree contiene commits que Claude Code no puede confirmar que estén guardados en otro lugar. Claude Code conserva el worktree y la fila de la sesión en lugar de destruir los commits sin que los veas. claude rm nombra la rama y los commits no enviados, e indica cómo proceder:

kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”
  2 unpushed commits on “claude/fix-login”: a1b2c3d “Fix login flow” and 1 more. They exist on no remote, so deleting the worktree would lose them.
  push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

Cuando Claude Code no puede resumir los commits, la línea de detalle dice The worktree has unpushed commits en su lugar. En agent view, la fila de la sesión muestra not deleted con la misma razón.

Los commits en un remoto no bloquean la eliminación. Tampoco los commits en la copia local de la rama predeterminada de tu remoto origin, siempre que esa rama esté activa en tu checkout principal, es decir, el propio directorio del repositorio en lugar de un worktree.

Qué hacer:

• Para conservar los commits, envía la rama del worktree, o fusiónala en la rama predeterminada activa en tu checkout principal, y luego elimina la sesión nuevamente
• Para descartar los commits, ejecuta el comando claude rm <id> --discard-unpushed que imprimió el mensaje, o presiona Ctrl+X dos veces nuevamente en la fila de la sesión en agent view. Esto elimina la sesión y el worktree junto con su rama, los commits no enviados y cualquier cambio sin commit. Si el worktree ha ganado un commit desde el rechazo, Claude Code lo conserva nuevamente y muestra el estado actualizado
• Cuando el mensaje dice que el worktree también está registrado por otra sesión terminada, eliminar nuevamente no lo descarta: envía los commits y luego elimina la sesión nuevamente

Antes de v2.1.268, claude rm ponía el resumen de commits en la propia línea kept. Cuando claude rm no podía resumir los commits, la línea kept decía worktree has commits that are not pushed anywhere en lugar del resumen.

Antes de v2.1.260, el mensaje no nombraba la rama ni los commits, y eliminar nuevamente se rechazaba de la misma manera: eliminar la sesión sin enviar los commits significaba eliminar el worktree tú mismo con git worktree remove --force <path> y luego ejecutar claude rm <id> nuevamente.

Antes de v2.1.248, la rama predeterminada activa en tu checkout principal no contaba: una rama que ya habías fusionado allí seguía activando este rechazo hasta que sus commits llegaran a un remoto.

El proceso host de la terminal murió

La terminal de cada sesión en segundo plano se ejecuta en un proceso host bajo el servicio en segundo plano, y ese proceso murió mientras el servicio aún mantenía su conexión, por lo que no se pudo acceder a la sesión.

En Linux y WSL, el servicio en segundo plano verifica cada proceso host cada pocos segundos, marca la sesión como fallida cuando el proceso ha salido pero su conexión con el servicio nunca se cerró, y muestra la razón en su fila en agent view:

terminal host process died — press Enter to restart

Desde el shell, claude attach <id> reinicia una sesión ya marcada como fallida por un host muerto, y en caso contrario imprime la causa y sale:

Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.

La conversación se guarda en cualquier caso.

Una fila que ejecuta un comando de shell muestra en cambio terminal host process died — its output is gone; the command was not run again, y claude attach imprime This command's terminal host process died — its output is gone and the command was not run again. Claude Code nunca vuelve a ejecutar el comando por ti.

Qué hacer:

• En agent view, presiona Enter en la fila fallida; la sesión se reinicia en un nuevo proceso host y la conversación se reanuda
• Desde el shell, ejecuta claude attach <id> nuevamente. Claude Code imprime Session <id>'s terminal host died — restarting it on a fresh one… y vuelve a abrir la sesión
• No puedes reiniciar una fila de comando de shell de esta manera; envía el comando nuevamente para volver a ejecutarlo

Antes de v2.1.247, un proceso host muerto podía pasar todas las verificaciones de actividad que ejecutaba el servicio en segundo plano, por lo que abrir la sesión mostraba opening… · esc to cancel indefinidamente y claude attach <id> esperaba sin reportar un error.

La sesión no responde

Abriste una sesión en segundo plano y el servicio en segundo plano aceptó la apertura, pero no llegó ninguna salida durante unos diez segundos, por lo que Claude Code concluye que el proceso que retransmite la terminal de la sesión no puede entregar salida, y termina el intento en lugar de seguir esperando.

En agent view, Claude Code ofrece un reinicio en el pie de página:

Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).

Desde el shell, claude attach <id> imprime la causa y sale:

Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).

Claude Code nunca reinicia por ti una fila que ejecuta un comando de shell, porque un reinicio volvería a ejecutar el comando.

Qué hacer:

• En agent view, presiona Enter nuevamente en la misma fila. Claude Code detiene el proceso que no responde y reinicia la sesión, y la conversación se reanuda. No se detiene nada sin esa segunda pulsación
• Desde el shell, ejecuta claude stop <id> y luego claude attach <id>
• Para una fila de comando de shell, presiona Ctrl+X en agent view o ejecuta claude stop <id> para detenerla; envía el comando nuevamente para volver a ejecutarlo

La sesión se detuvo mientras el respawn estaba en curso

Abriste una sesión en segundo plano cuyo proceso no se estaba ejecutando, y mientras Claude Code la reiniciaba, otro proceso de Claude Code la detuvo, por ejemplo claude stop en otra terminal. Claude Code mantiene la sesión detenida:

Session <id> was stopped while the respawn was in flight

Abrir una sesión que acabas de enviar, mientras su proceso aún se está iniciando, espera al proceso en su lugar. Antes de v2.1.246, abrirla en ese momento podía detenerla y mostrar este mensaje.

Qué hacer:

• Si no detuviste la sesión, abre su fila nuevamente en agent view o ejecuta claude respawn <id> para reiniciarla
• Si la detuviste tú mismo, no queda nada por hacer: la sesión permanece detenida

El agente de la sesión ya no está disponible

Reanudaste una sesión que estaba ejecutando un agente personalizado, iniciado con --agent o el ajuste agent, y Claude Code no encontró un agente con ese nombre. Busca primero en el directorio original de la sesión, cuando has confiado en ese espacio de trabajo, y luego en el directorio desde el que reanudas. La sesión se reanuda de todos modos, pero con las herramientas predeterminadas, por lo que las restricciones de herramientas del agente ya no se aplican:

This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.

La advertencia nombra solo los directorios en los que Claude Code buscó, y aparece en la conversación reanudada ya sea que despiertes una sesión en segundo plano, ejecutes /resume o claude --resume, o reanudes en modo no interactivo, donde también va a stderr. Las sesiones que usan --input-format stream-json no la muestran, porque el Agent SDK proporciona los agentes después del inicio.

Claude Code no guarda la alternativa en la sesión, por lo que la advertencia se repite en cada reanudación hasta que actúes. El agente integrado claude no activa la advertencia, ya que recurrir al conjunto de herramientas predeterminado no cambia nada para él. Antes de v2.1.216, Claude Code continuaba silenciosamente como el agente predeterminado, y la búsqueda cubría solo el directorio desde el que reanudabas, por lo que un agente con alcance de proyecto se perdía en cualquier reanudación desde otro directorio.

Qué hacer:

• Vuelve a crear el archivo del agente en .claude/agents/<name>.md en el proyecto de la sesión, o en ~/.claude/agents/<name>.md para un agente personal, y luego reanuda nuevamente
• O reanuda con --agent <name> nombrando un agente que sí exista, para ejecutar la sesión como ese agente en su lugar
• Si el agente tiene alcance de proyecto y no has confiado en el directorio original de la sesión, ejecuta Claude Code allí una vez, acepta el diálogo de confianza y luego reanuda nuevamente

Errores del lanzador CLAUDE\_CODE\_PROCESS\_WRAPPER

CLAUDE_CODE_PROCESS_WRAPPER está configurado y su valor no se puede usar, por lo que Claude Code se niega a iniciar el proceso afectado en lugar de ejecutarlo sin el lanzador. Los problemas de configuración se reportan con un mensaje que comienza con el nombre de la variable e indica la razón, por ejemplo:

CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

Un lanzador que se inicia pero sale sin reemplazarse a sí mismo con Claude Code hace fallar la sesión que estaba iniciando, y la fila de la sesión en agent view reporta que el lanzador must exec, not daemonize, seguido de lo que el lanzador haya impreso. Una sesión que no puede iniciarse o comunicarse con el servicio en segundo plano debido al lanzador reporta el problema del lanzador como la razón dentro de Couldn't reach the background service (...).

Qué hacer:

• Configura la variable con la ruta absoluta de un ejecutable que termine llamando a exec "$@". Consulta el contrato del lanzador para ver el contrato completo
• Revisa /status, que muestra el comando de lanzamiento resuelto en su entrada Self-exec y advierte cuando el servicio en segundo plano en ejecución no coincide con él, o ejecuta claude daemon status desde un shell
• Después de corregir el valor en el bloque env de la configuración, reinicia el servicio en segundo plano con claude daemon stop --any para que el siguiente envío inicie uno envuelto por el lanzador

EUNKNOWN al iniciar una sesión en segundo plano

Windows se negó a iniciar un programa con un código de error que no tiene nombre estándar, por lo que el fallo aparece como EUNKNOWN. La causa habitual es una política de restricción de software, como Group Policy o AppLocker, que bloquea el programa que se está iniciando. El error aparece cuando inicias una sesión en segundo plano con /background o claude --bg:

Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

En algunas cuentas el mensaje dice daemon en lugar de background service.

En una instalación con npm, un EUNKNOWN que aparece mientras npm install -g @anthropic-ai/claude-code está reemplazando el binario tiene la misma causa que EACCES durante una reinstalación y desaparece cuando reintentas después de que la instalación termina.

Claude Code inicia el servicio en segundo plano a través de PowerShell para que el servicio sobreviva al cierre de la terminal, usando PowerShell 7 cuando está instalado y Windows PowerShell 5.1 en caso contrario. Cuando ninguno de los dos PowerShell puede ejecutarse, Claude Code inicia el servicio directamente, por lo que una política que bloquea solo PowerShell no causa este error.

Antes de v2.1.212, Claude Code usaba solo Windows PowerShell 5.1 para iniciar el servicio, por lo que cualquier máquina donde Group Policy bloqueaba PowerShell 5.1 fallaba con Couldn't start the session — EUNKNOWN: unknown error, uv_spawn, incluso con PowerShell 7 instalado.

Qué hacer:

• Si el mensaje dice Couldn't start the session, actualiza a v2.1.212 o posterior. En versiones anteriores también puedes ejecutar primero claude daemon run en una terminal aparte y luego iniciar la sesión en segundo plano nuevamente. Ese comando ejecuta el servicio en segundo plano en primer plano en la terminal, por lo que el servicio dura solo mientras esa terminal permanezca abierta.
• Si una instalación con npm estaba reemplazando el binario, espera a que termine y luego inicia la sesión en segundo plano nuevamente
• Si el error aparece en v2.1.212 o posterior sin que se esté ejecutando ninguna instalación con npm, consulta con tu administrador de Windows si una política de restricción bloquea el ejecutable de Claude Code
• Si el servicio en segundo plano se detiene cuando cierras la terminal, Claude Code lo inició sin PowerShell. Instala PowerShell 7, o pide a tu administrador que desbloquee PowerShell, para que el servicio pueda sobrevivir a la terminal.

EACCES al iniciar una sesión en segundo plano

Claude Code no pudo ejecutar su propio binario para iniciar el servicio en segundo plano que aloja las sesiones en segundo plano. En una instalación con npm, esto generalmente significa que npm install -g @anthropic-ai/claude-code estaba reemplazando el binario en ese momento, ya sea que lo ejecutaras tú o el actualizador automático. El error aparece cuando abres una sesión desde agent view:

Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'

Cuando inicias una sesión con /background o claude --bg, la misma razón aparece dentro de Couldn't reach the background service (...). Durante el mismo periodo de reinstalación el error puede nombrar otro código, como ENOENT o ENOEXEC, o EUNKNOWN o EPERM en Windows; un EUNKNOWN que persiste tras varios reintentos tiene una causa diferente.

En una instalación con npm, Claude Code espera a que la reinstalación termine y reintenta por su cuenta: hasta diez segundos, y hasta dos minutos mientras una instalación de Claude Code con npm siga visiblemente en ejecución en la máquina, lo que cubre el caso de otro proceso de Claude Code que descarga una actualización. Cuando la instalación supera esa espera, el fallo nombra la actualización en lugar del código de error sin más:

Claude Code is being updated by npm on this machine (still not runnable after 2 min, EACCES) — try again when the update finishes

Antes de v2.1.257, la espera terminaba a los diez segundos en todos los casos, por lo que este error aparecía mientras otro proceso de Claude Code aún estaba descargando una actualización. Antes de v2.1.246, Claude Code fallaba de inmediato, sin esperar.

Qué hacer:

• Espera unos segundos y luego abre la sesión o haz el envío nuevamente. Cuando el mensaje dice que Claude Code se está actualizando, reintenta después de que la actualización termine.
• Si el error persiste sin que se esté ejecutando ninguna instalación con npm, tu usuario no puede ejecutar el binario instalado. Revisa sus permisos y los de su directorio, o reinstala Claude Code.

El servicio en segundo plano salió antes de estar disponible

El proceso que Claude Code inició como el servicio en segundo plano salió antes de aceptar conexiones, por lo que Claude Code no pudo abrir tu sesión. Cuando el servicio imprimió un error antes de salir, la razón entre paréntesis indica el código de salida o la señal y la primera línea que imprimió el servicio, que nombra lo que lo detuvo:

Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'

Cuando abres una sesión desde agent view, la misma razón aparece después de Couldn't start the background service —. Cuando el servicio no imprimió nada antes de salir, el mensaje dice nothing on stderr en su lugar.

Claude Code reporta el fallo con la línea de error del servicio. Antes de v2.1.246, el fallo aparecía solo después de una espera de 45 segundos, como background service did not become reachable within 45s, sin la línea de error del servicio.

Dos razones citadas tienen causas conocidas:

• Error: claude native binary not installed.: una instalación con npm estaba reemplazando el binario de Claude Code en ese momento, por lo que el servicio ejecutó el marcador de posición de npm en su lugar. Reintenta después de que la instalación termine; si la línea persiste sin ninguna instalación en ejecución, completa la instalación con npm. Antes de v2.1.257, una autoactualización con npm en macOS producía este fallo en cada inicio durante el periodo de instalación.
• nothing on stderr con código de salida 1, en cada inicio, en Windows: daemon.lock nombra un proceso al que Claude Code no puede enviar señales ni demostrar que ya no existe, por lo que cada nuevo servicio concluye que otro mantiene el bloqueo y sale. Un bloqueo cuyo escritor Claude Code puede demostrar que ya no existe se reemplaza automáticamente y no produce este fallo. Cuando el fallo se repite en cada inicio, elimina ~/.claude/daemon.lock y luego abre la sesión o haz el envío nuevamente. Antes de v2.1.257, un bloqueo así impedía cada inicio hasta que eliminaras el archivo.

Qué hacer:

• Si el mensaje cita una línea, corrige lo que nombra y luego abre la sesión o haz el envío nuevamente. El siguiente intento vuelve a iniciar el servicio
• Ejecuta claude daemon status para verificar si hay un servicio en ejecución ahora

El directorio de trabajo ya no existe al iniciar una sesión en segundo plano

El directorio en el que iniciaste una sesión en segundo plano se eliminó mientras la sesión se estaba iniciando. Claude Code no inicia la sesión, y el mensaje nombra el directorio faltante:

Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

Antes de v2.1.257, la sesión parecía iniciarse y luego se mostraba en agent view como una fila fallida con la misma razón.

Antes de v2.1.281, este mensaje también aparecía cuando el directorio ya no existía antes de que iniciaras la sesión. Ese caso reporta could not be resolved on disk.

Qué hacer:

• Vuelve a crear el directorio que nombra el mensaje, o haz el envío desde un directorio que exista, y luego inténtalo de nuevo

Espacio de trabajo no confiable al enviar una sesión en segundo plano

Iniciaste o reiniciaste una sesión en segundo plano en un directorio en el que no has confiado, y el diálogo de confianza del espacio de trabajo no pudo aparecer para preguntarte. Claude Code no inicia la sesión:

Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.

Desde una terminal en el propio directorio de la sesión, el mismo comando muestra el diálogo de confianza en su lugar e inicia la sesión una vez que aceptas. Este mensaje aparece donde no puede mostrarse ningún diálogo, como en un script, o cuando reinicias una sesión desde un directorio distinto al suyo.

Dos variantes nombran una causa diferente:

• The home directory is trusted one session at a time: el directorio de la sesión es tu directorio home. Claude Code nunca guarda la confianza para el directorio home, por lo que haber aceptado el diálogo allí en una sesión anterior no cuenta.
• <path> could not be resolved on disk: Claude Code no pudo encontrar el directorio de la sesión en el disco.

Antes de v2.1.286, en Windows, este mensaje también podía aparecer en un directorio en el que ya habías confiado, si su registro de confianza se había guardado con la ruta en mayúsculas y minúsculas diferentes. Actualiza a v2.1.286 o posterior.

Qué hacer:

• Ejecuta claude en el directorio que nombra el mensaje y acepta el diálogo de confianza, y luego ejecuta el comando nuevamente
• Para el mensaje del directorio home, ejecuta el comando desde una terminal en tu directorio home para que el diálogo pueda aparecer, o inicia la sesión desde un directorio de proyecto en su lugar
• Para el mensaje could not be resolved on disk, vuelve a crear el directorio, o inicia una nueva sesión desde un directorio que exista

Errores de wrapper e IDE

Estos errores provienen del programa que inició Claude Code para usted, como una extensión de IDE o una aplicación del Agent SDK, en lugar de provenir de Claude Code en sí.

El proceso de Claude Code salió con código N

El proceso claude subyacente salió con un código distinto de cero. El código de salida por sí solo no indica qué falló: el error real está en la propia salida del proceso, que el wrapper añade cuando la capturó y de lo contrario mantiene en sus registros.

Error: Claude Code process exited with code 1

En Windows, la compilación nativa puede salir con código 4294967295 justo después de que se completa un turno. Cuando esa salida llega a un límite de turno, sin mensaje esperando y sin tarea de fondo ejecutándose, la extensión de VS Code cierra la sesión silenciosamente en lugar de mostrar este error. Su siguiente mensaje reanuda la conversación.

Antes de v2.1.273, la extensión mostraba el error para esa salida en cada límite de turno, aunque nada se perdiera.

Qué hacer:

• En VS Code, siga el enlace Ver registros de salida que se muestra con el error para ver el fallo subyacente
• En una aplicación del Agent SDK, capture el error alrededor de su bucle de mensajes. Las entradas bajo Salida del proceso CLI cubren lo que su código recibe en cada lenguaje de SDK.
• Ejecute claude en una terminal en el mismo proyecto. El fallo generalmente se reproduce allí con su mensaje de error real, que luego puede buscar en esta página.
• Ejecute claude doctor en una terminal para verificar la instalación y la configuración

No se pudo localizar la CLI de Claude en PATH

La extensión de VS Code muestra este error en Windows cuando abre Claude Code en la terminal integrada, el shell de la terminal es PowerShell y la extensión no puede encontrar el ejecutable claude instalado en PATH. La extensión se niega a iniciar Claude Code hasta que encuentre el claude instalado en PATH.

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH. Launching by name in a PowerShell terminal would run a 'claude' from the open folder instead of the installed CLI, so the launch was blocked. Make sure the Claude CLI's install directory is on your system PATH (not only your PowerShell profile), then restart VS Code and try again. VS Code reads PATH when it starts, so PATH changes take effect only after a restart.

Qué hacer:

• Abra una nueva ventana de PowerShell fuera de VS Code y ejecute where.exe claude. Si no imprime una ruta, la CLI no está en su PATH: agregue su directorio de instalación siguiendo Verifique su PATH. Si imprime una ruta, la entrada proviene de su perfil de PowerShell o de un cambio de PATH que VS Code aún no ha recogido; los próximos dos pasos cubren esos casos.
• Establezca la entrada de PATH como una variable de entorno de usuario o sistema, no en su perfil de PowerShell. La extensión no ejecuta su perfil, por lo que una edición de PATH que vive solo allí nunca la alcanza.
• Reinicie VS Code después de cambiar PATH. La extensión verifica el PATH que VS Code capturó al inicio, por lo que un cambio de PATH solo tiene efecto después de un reinicio.

La conexión a Claude Code terminó antes de que este mensaje se completara

La extensión de VS Code envió su mensaje al proceso claude, y la conexión terminó sin un error antes de que el proceso lo reconociera o lo completara. La extensión no puede saber si el mensaje fue procesado, por lo que le pide que lo envíe de nuevo:

The connection to Claude Code ended before this message completed — it may not have been processed, so please send it again.

Qué hacer:

• Envíe el mensaje de nuevo. El siguiente mensaje inicia un nuevo proceso claude que reanuda la conversación.
• Si se repite, ejecute claude en una terminal en el mismo proyecto. Un fallo que sigue terminando el proceso generalmente se reproduce allí con su mensaje de error real.

Advertencias y errores de Rewind

Estos mensajes provienen de una restauración de código /rewind. Restored the code, but skipped N files es una advertencia que indica que Claude Code omitió algunas rutas. No files were restored es un error que significa que no restauró nada.

Restored the code, but skipped files

Una restauración de código /rewind omitió una o más rutas rastreadas en lugar de escribir o eliminar a través de ellas. Claude Code omite una ruta cuando:

• es, o se convirtió en, un enlace simbólico, enlace duro u otro archivo no regular
• su directorio cambió desde el punto de control
• su copia de seguridad no se puede leer de forma segura

Las rutas omitidas mantienen su contenido actual. Antes de v2.1.216, /rewind escribía y eliminaba a través de enlaces en rutas rastreadas, y no informaba de una restauración parcial.

Restored the code, but skipped 2 files: the tracked path is (or became) a link or other non-regular file, its directory changed since the checkpoint, or its backup could not be safely read. Skipped files were left untouched — run with --debug for the paths.

Qué hacer:

• Identifique qué archivos se omitieron para poder manejar cada uno con los pasos a continuación. El mensaje solo proporciona un recuento; el registro de depuración en ~/.claude/debug/<session-id>.txt nombra cada ruta omitida mientras se ejecuta la restauración, así que active el registro de depuración con /debug antes de su próxima restauración. En macOS o Linux, puede encontrar los enlaces directamente: find . -type l para enlaces simbólicos y find . -type f -links +1 para archivos con enlaces duros.
• Si un archivo omitido es un enlace que creó a propósito, como un archivo de configuración administrado por un gestor de dotfiles o un archivo con enlace duro por herramientas como pnpm, la restauración dejó su contenido intacto. Para deshacer los cambios de la sesión en él, pida a Claude que revierta la edición o edite el archivo usted mismo
• Si no creó el enlace, inspeccione la ruta antes de confiar en su contenido

No files were restored

Claude Code muestra este mensaje cuando restaura código con /rewind y no puede restaurar ninguno de los archivos en ese punto de control. Para cada archivo, falta la copia de seguridad que Claude Code guardó antes de editarlo, o Claude Code no pudo escribir o eliminar el archivo.

Failed to restore the code:
No files were restored: 1 file failed (backup missing, or the file could not be updated)

Claude Code elimina las copias de seguridad de una sesión en el barrido de retención, por defecto aproximadamente 30 días después de que la sesión guardara una por última vez. Si reanuda una sesión después de eso, /rewind aún enumera sus puntos de control, pero la restauración a uno de ellos puede fallar con este error. Si el mensaje también dice N paths were skipped for link safety, consulte Restored the code, but skipped files para esas rutas.

Cuando bifurca una sesión, por ejemplo con --fork-session o /branch, Claude Code copia las copias de seguridad de la sesión original en la bifurcación. Cuando Claude Code no puede copiar una copia de seguridad, por ejemplo porque el disco está lleno, esa copia de seguridad falta en la bifurcación. La restauración a un punto de control que la necesita puede fallar con este error.

Qué hacer:

• Deshaga los cambios de otra manera: pida a Claude que revierta sus ediciones, o restaure los archivos desde el control de versiones. Cuando las copias de seguridad desaparecen, ejecutar /rewind nuevamente falla de la misma manera.
• Si Claude Code no pudo escribir o eliminar un archivo, corrija lo que bloquea la escritura, como los permisos de archivo, luego ejecute /rewind nuevamente.
• Para mantener las copias de seguridad más tiempo en futuras sesiones, aumente cleanupPeriodDays.

Antes de v2.1.260, Claude Code omitía silenciosamente los archivos cuyas copias de seguridad faltaban, y la restauración parecía tener éxito.

Advertencias de guardado de sesión

Claude Code muestra estas advertencias en una línea persistente debajo del cuadro de entrada cuando no está guardando la transcripción de su sesión. La sesión sigue funcionando de cualquier forma; las advertencias le indican que la sesión puede faltar en --resume más adelante.

Las escrituras de transcripción están fallando

Claude Code guarda la transcripción en disco mientras trabaja, y sus escrituras en el archivo de transcripción están fallando. El mensaje nombra la causa con el código de error subyacente, por ejemplo un disco lleno:

Transcript writes are failing (disk full — ENOSPC) · recent messages may not be saved for resume

La advertencia aparece en diferentes puntos dependiendo del error:

• En el primer fallo para condiciones que no se resuelven por sí solas: un disco lleno, una cuota de disco excedida, un sistema de archivos de solo lectura, una ruta que supera el límite de longitud del sistema de archivos, o, en macOS y Linux, un error de permiso
• Después de fallos repetidos que abarcan al menos un minuto para todo lo demás, incluidos errores de permiso en Windows, donde un escaneo antivirus puede fallar una única escritura que luego tiene éxito al reintentar

Antes de v2.1.217, Claude Code descartaba las escrituras fallidas sin una advertencia, y un --resume posterior que faltaban mensajes recientes era el primer signo.

Qué hacer:

• Corrija la condición que nombra el código de error: libere espacio en disco para ENOSPC; aumente o borre la cuota para EDQUOT; restaure el acceso de escritura a la ubicación de la transcripción para EACCES, EPERM, o EROFS
• La advertencia se borra por sí sola en la siguiente escritura exitosa; no se necesita reiniciar
• Los mensajes enviados mientras se mostraba la advertencia aún pueden faltar cuando reanude la sesión más adelante

El guardado de transcripción está desactivado porque CLAUDE\_CODE\_SKIP\_PROMPT\_HISTORY está configurado

Esta sesión comenzó con CLAUDE_CODE_SKIP_PROMPT_HISTORY configurado, por lo que Claude Code no escribe transcripción ni historial de indicaciones para ella:

Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set · --resume will not find this session; if unintended, unset it and restart

La variable es una exclusión intencional para sesiones de scripts efímeros, pero también puede llegar a una sesión a través de un perfil de shell, un script contenedor, o un proceso padre que la exportó.

Qué hacer:

• Si configuró la variable a propósito, no se necesita ninguna acción; el aviso confirma que la sesión no aparecerá en --resume, --continue, o en el historial de flecha hacia arriba
• Si no lo hizo, elimine la variable del shell o script que inicia claude, luego inicie una nueva sesión. Los mensajes de la sesión actual no se guardan retroactivamente.

El guardado de transcripción está desactivado debido a un marcador CLAUDE\_CODE\_CHILD\_SESSION heredado

Claude Code establece CLAUDE_CODE_CHILD_SESSION en los subprocesos que genera, y trata una sesión interactiva que lo hereda como anidada: Claude Code no guarda transcripción para ella, por lo que las sesiones que Claude mismo inicia no llenan su lista de --resume. Este aviso significa que su sesión actual heredó el marcador:

Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts

El aviso es esperado cuando ejecutó claude desde dentro de otra sesión de Claude Code; señala una clasificación errónea cuando el marcador se filtró a través de un intermediario de larga duración, por ejemplo una terminal, sesión de screen, o lanzador que una sesión de Claude Code originalmente inició.

Dentro de tmux, Claude Code detecta un marcador que llegó a través del entorno global del servidor tmux y sigue guardando, por lo que este aviso no aparece para ese caso.

Qué hacer:

• Si inició esta sesión desde dentro de otra sesión de Claude Code a propósito, no se necesita ninguna acción
• Si esta es una sesión de nivel superior, salga y reinicie con CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 configurado. El guardado se aplica desde el reinicio, por lo que los mensajes enviados antes no se guardan.
• Para corregir futuros lanzamientos desde la misma terminal o lanzador, elimine CLAUDE_CODE_CHILD_SESSION de su entorno

Advertencias de configuración

Claude Code escribe la mayoría de estos mensajes en stderr, no en la conversación, y escribe la mayoría de ellos al iniciar. Una entrada lo indica cuando su mensaje aparece en otro lugar, como en el registro de depuración o como un aviso de inicio en la vista de conversación, o en otro momento, como la línea de diagnóstico de modelo no reconocido en el momento de la solicitud.

Claude Code se cerró después de un error de interfaz irrecuperable

Claude Code imprime este mensaje cuando se cierra porque su interfaz de terminal encontró un error del que no puede recuperarse, en cualquiera de los renderizadores. La segunda oración aparece solo cuando el error ocurrió mientras el renderizador de pantalla completa se estaba iniciando:

Claude Code exited after an unrecoverable interface error (<error>). It happened while the fullscreen renderer was starting, so the next launch will use the classic renderer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces that any time).

Qué hacer:

• Inicie Claude Code de nuevo. Para retomar la conversación, ejecute claude --resume en el mismo directorio.
• Si el mensaje menciona el renderizador de pantalla completa, Fullscreen rendering dice qué hace el siguiente inicio, que depende de cómo activó la pantalla completa, y cómo intentar pantalla completa de nuevo o mantener el renderizador clásico.

Antes de v2.1.236, Claude Code se cerraba sin imprimir un mensaje después de este tipo de error.

Las descripciones de agentes superan el límite de 15.0k tokens

Claude Code muestra esta advertencia como un aviso de inicio en la vista de conversación en lugar de en stderr. Las descripciones combinadas de sus subagentes, excepto las integradas, superan 15,000 tokens según las estima Claude Code. Cada agente cuenta su nombre más su frontmatter description. Claude Code carga cada agente independientemente de si el total supera el límite, por lo que la advertencia no cambia lo que se carga.

Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/

Qué hacer:

• Acorte el frontmatter description de sus archivos de agente, o pida a Claude que los recorte por usted.
• Elimine los archivos de agente que ya no utiliza.

Una skill, comando o flujo de trabajo no se cargó porque su nombre está reservado

Una carpeta de skill, un frontmatter name, un archivo o subcarpeta en .claude/commands/, o un flujo de trabajo guardado utiliza el nombre anthropic-skills o un nombre que comienza con anthropic-skills:. Claude Code reserva ese nombre para skills sincronizadas desde claude.ai y no carga ese elemento.

Claude Code muestra esta advertencia como un aviso de inicio en la vista de conversación en lugar de en stderr:

Not loaded: rename .claude/skills/anthropic-skills, then restart — its name uses "anthropic-skills", a name reserved for the skills synced from your claude.ai account

El aviso nombra qué cambiar para el primer elemento que rechazó: una carpeta o archivo para renombrar, una línea name: para editar, o un flujo de trabajo para renombrar. Cuando se rechazó más de un elemento, el aviso termina con un recuento como · 2 more, y el registro de depuración nombra cada uno.

Qué hacer:

• Renombre el elemento que nombra el aviso, o edite la línea name: a la que apunta, luego reinicie la sesión.

Antes de v2.1.282, Claude Code cargaba skills y comandos con estos nombres.

El espacio de trabajo no ha sido confiable

Claude Code encontró reglas permissions.allow o entradas permissions.additionalDirectories en el archivo .claude/settings.json o .claude/settings.local.json del proyecto y no las aplicó, porque las reglas de permiso del proyecto requieren confianza del espacio de trabajo. El recuento, el nombre de la configuración y el archivo nombrado en el mensaje varían según su configuración. Las reglas deny y ask no se ven afectadas.

Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

Qué hacer:

• Ejecute claude en el directorio y acepte el diálogo de confianza. Project allow rules and workspace trust dice qué carpeta cubre esa aceptación.
• En modo no interactivo con -p no se muestra ningún diálogo. Establezca la entrada hasTrustDialogAccepted en ~/.claude.json usando la clave exacta projects que imprime el mensaje.
• Si el mensaje menciona .claude/settings.local.json e inició Claude Code fuera de un repositorio git o en su directorio de inicio, actualice a v2.1.200 o posterior. Las versiones 2.1.196 a 2.1.199 trataban su propio .claude/settings.local.json como suministrado por el repositorio en esos espacios de trabajo. En v2.1.207 y posterior, actualizar no es suficiente fuera de un repositorio git si no ha confiado en la carpeta: determinar que una carpeta no está dentro de un repositorio ejecuta git, y Claude Code ejecuta esa verificación solo después de que acepte el diálogo de confianza, así que use el primer paso. Su directorio de inicio y cualquier otro directorio de configuración están exentos y no esperan el diálogo. Consulte Project allow rules and workspace trust.

El directorio de trabajo es una ruta de red

Claude Code no agrega rutas de red como directorios de trabajo. Buscar una ruta de red puede contactar al host que nombra, y en Windows ese contacto puede enviar al host sus credenciales, por lo que Claude Code rechaza la ruta sin buscarla. Ve este mensaje cuando ejecuta /add-dir con tal ruta, o como una advertencia al iniciar. Cuando aparece al iniciar, Claude Code se inicia sin ese directorio.

\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).

Las rutas que Claude Code rechaza de esta manera incluyen:

• Recursos compartidos UNC como \\server\share
• Rutas de montaje automático como /net/<host>, a menos que haya iniciado Claude Code desde un directorio bajo el montaje automático de ese host
• Rutas locales que alcanzan una ubicación de red a través de un enlace simbólico o unión

Las letras de unidad asignadas y las rutas \\wsl$ no cuentan como rutas de red.

Qué hacer:

• En Windows, asigne el recurso compartido a una letra de unidad, por ejemplo con net use Z: \\server\share, y pase la unidad al iniciar con claude --add-dir Z:\.
• En macOS o Linux, monte el recurso compartido en una ruta local y agregue esa ruta en su lugar.
• Si la ruta está en permissions.additionalDirectories, elimínela del archivo de configuración que la enumera.

Antes de v2.1.257, Claude Code aceptaba una ruta de red accesible como directorio de trabajo.

La configuración remota administrada no se pudo cargar

Su sesión es elegible para configuración administrada por servidor, pero Claude Code no pudo obtenerla o no pudo aplicar lo que el servidor devolvió, por lo que muestra esta advertencia en sesiones interactivas.

La causa entre paréntesis nombra lo que falló, como network error, request timed out o authentication rejected (401). La causa no setting in the server response could be applied as written significa que el servidor respondió pero ninguna de las configuraciones que devolvió pasó validación. Antes de v2.1.282, esta causa decía server returned invalid settings.

El resto de la línea dice qué política ejecuta la sesión:

• Configuración almacenada en caché de una obtención anterior exitosa: Claude Code ejecuta la sesión en esa política almacenada en caché, excepto las variables de entorno retenidas, y la línea dice using cached policy.
• Sin caché: Claude Code ejecuta la sesión sin configuración administrada por servidor, y la línea dice no remote policy applied.

Qué hacer:

• Actúe sobre la causa que nombra el mensaje: para una causa de red, verifique que esta máquina pueda alcanzar api.anthropic.com; para una causa de autenticación, verifique su inicio de sesión con /status
• Para no setting in the server response could be applied as written, pida a su administrador que corrija la configuración en el servidor
• Ejecute /status o claude doctor para el diagnóstico completo

Antes de v2.1.248, Claude Code reportaba una obtención de configuración fallida solo en el registro de depuración.

La configuración administrada no fue aprobada

La configuración administrada por servidor de su organización incluye configuración que necesita su aprobación, y usted rechazó el diálogo de aprobación de seguridad, por lo que Claude Code se cierra sin aplicarla:

Managed settings were not approved; exiting without applying them.

Qué hacer:

• Inicie Claude Code de nuevo y apruebe el diálogo para continuar bajo la configuración de su organización. Un diálogo rechazado no se recuerda, por lo que aparece de nuevo en el siguiente inicio.
• Si no está seguro acerca de una configuración que enumera el diálogo, pregunte a quien mantenga la configuración administrada de su organización antes de aprobar

La configuración administrada bloquea el modelo predeterminado

Su configuración administrada de la organización bloquea el modelo al que se resuelve la opción Predeterminada y cada modelo al que podría reducirse. Una sesión que comenzaría en la opción Predeterminada se cierra al iniciar en lugar de ejecutar un modelo bloqueado. Qué mensaje ve depende de la configuración que lo bloquea. Cuando una lista deniedModels lo bloquea, el mensaje dice:

Claude Code can't start: your organization's managed settings block the default model (claude-opus-5-5) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".

Cuando una lista availableModels con availableModelsMatch establecido en "exact" la omite, el mensaje dice:

Claude Code can't start: your organization allows only the models listed in "availableModels", and none of them can be used as the default model (claude-opus-5-5 isn't listed). Ask your administrator to update "availableModels".

Qué hacer:

• Si administra la configuración, agregue un modelo que sus usuarios puedan ejecutar a availableModels, o estreche las entradas deniedModels que bloquean cada alternativa. Block specific models or versions describe cómo la opción Predeterminada se reduce
• Si no las administra, envíe el mensaje a su administrador. Sus propios archivos de configuración no pueden ampliar una lista availableModels o deniedModels administrada

La configuración administrada no permite este proveedor de API

Su configuración administrada de la organización establece una lista allowedProviders, y el proveedor de API de la sesión no está en ella o la sesión usa un endpoint que no está fijado de la manera que esa entrada requiere. Claude Code se niega al iniciar, antes de un inicio de sesión, o cuando la sesión contacta a continuación la API. El mensaje comienza con los proveedores permitidos:

Your organization's managed settings allow Claude Code to use: Anthropic API, Amazon Bedrock.

Cuando la lista está vacía, el mensaje dice en su lugar:

Your organization's managed settings allow Claude Code to use no API provider at all (allowedProviders is an empty list), so it cannot start on this machine.

Cuando cada entrada no es reconocida, el paréntesis dice en su lugar (allowedProviders lists only unrecognized entries).

Qué hacer:

• Siga los pasos To continue: del mensaje
• Si administra la configuración, las líneas del mensaje que comienzan con Admins: nombran la entrada a agregar o el valor a fijar, y la entrada allowedProviders dice qué bloque env de qué fuente puede fijarlo

El servidor MCP está bloqueado por la política administrada empresarial

Seleccionó Reconnect en un servidor en /mcp, o activó un servidor deshabilitado allí, y una configuración que restringe servidores MCP bloquea ese servidor. Claude Code se niega a conectarlo y muestra:

MCP server <name> is blocked by enterprise managed policy

Cualquiera de estas configuraciones puede producir el mensaje:

• Una entrada deniedMcpServers que coincida con el servidor, incluida una en su propio ~/.claude/settings.json o en el .claude/settings.json del proyecto
• Una lista allowedMcpServers que el servidor no coincida
• strictPluginOnlyCustomization con mcp bloqueado, que bloquea servidores configurados en ~/.claude.json y .mcp.json
• disableClaudeAiConnectors, cuando el servidor es un conector de claude.ai

Qué hacer:

• Verifique sus propios archivos de configuración de usuario y proyecto para una de estas configuraciones y cámbiela o elimínela
• Si ninguna de sus propias configuraciones explica el bloqueo, pregunte a su administrador qué configuración administrada bloquea el servidor

Antes de v2.1.257, Reconnect y re-habilitar en /mcp podían conectar un servidor que una actualización de política a mitad de sesión bloqueó.

El documento de configuración administrada no se pudo analizar

Su organización implementa configuración administrada, y uno de los documentos implementados está presente pero no se puede analizar como un objeto JSON, por lo que Claude Code se cierra con código 1 al iniciar en lugar de ejecutarse sin la política que lleva el documento. La línea nombra la fuente fallida antes del mensaje:

/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.

La fuente es una de:

• La ruta del archivo managed-settings.json o un archivo drop-in bajo managed-settings.d
• El perfil de preferencias administradas de macOS, per-user managed preferences o device-level managed preferences
• El valor del registro de Windows, Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings

Find entries Claude Code dropped enumera lo que hace que cada fuente sea no analizable.

Claude Code se niega a iniciar incluso cuando otra fuente de administrador entrega una política válida. Ve este error en sesiones interactivas, claude -p, sesiones del SDK de agente, sesiones en segundo plano, y la mayoría de subcomandos, claude doctor incluido. El rechazo falla cerrado a propósito: la configuración en un documento que Claude Code no puede analizar no se puede aplicar, e iniciar de todas formas ejecutaría sesiones sin los controles de la organización.

Un problema de esquema en un documento analizable no produce este error. Find entries Claude Code dropped cubre qué hace Claude Code con uno.

Cuando existe un directorio managed-settings.d/ pero no se puede enumerar, Claude Code reporta Managed settings drop-in directory could not be read: seguido del error subyacente en su lugar. Find entries Claude Code dropped cubre cuándo una falla de lectura se cierra al iniciar.

Qué hacer:

• Si administra la máquina, corrija el documento nombrado para que se analice como un objeto JSON, o elimine el archivo, perfil o valor del registro. Un managed-settings.json vacío cuenta como {} y no bloquea el inicio.
• Si no lo hace, pida a su administrador que corrija el documento implementado. Nada en sus propios archivos de configuración causa o borra este error.

No se pudo leer la configuración de política administrada

Su organización implementa configuración administrada, y una de las fuentes implementadas existe pero no se pudo leer, por una razón como un error de E/S en lugar de que el sistema operativo niegue la lectura. Sin otra fuente de administrador suministrando una política, Claude Code se cierra al iniciar en lugar de ejecutarse sin la política que la fuente puede llevar:

Unable to read managed policy settings.
This machine may require organization login enforcement, but the policy file failed to load.
Contact your administrator.

Detail: <source>: <reason>

En el mismo estado, los flujos de inicio de sesión, las solicitudes de API de una sesión que ya se está ejecutando, y el servidor claude gateway se rechazan con una variante de la primera línea que nombra allowedProviders.

Una lectura que el sistema operativo negó, como en un archivo de solo raíz, no produce esta salida: la sesión se inicia sin las políticas de esa fuente. Para una fuente que no se puede analizar, Claude Code se cierra con un mensaje diferente que nombra la fuente.

Qué hacer:

• Si administra la máquina, corrija el problema que nombra la línea Detail: para que la fuente implementada se pueda leer, o elimine la fuente
• Si no lo hace, envíe el mensaje a su administrador. Nada en sus propios archivos de configuración causa o borra este error

Antes de v2.1.285, solo las sesiones que iniciaron sesión con credenciales de claude.ai o Claude Console se cerraban con este mensaje, y una lectura que el sistema operativo negó también lo produjo.

otelHeadersHelper falló

Claude Code muestra esta advertencia como una notificación en la interfaz de terminal, una vez por sesión interactiva, cuando el script otelHeadersHelper falla o imprime salida que no cumple con los requisitos del script.

Mientras el script sigue fallando, las exportaciones fallan y su backend de telemetría no recibe nada de la sesión.

El texto después de See /status: dice qué falló, como el código de salida del script seguido de su salida de error:

otelHeadersHelper failed; telemetry is not being exported. See /status: exited 1: token service unreachable

Qué hacer:

• Ejecute /status para leer el detalle de la falla.
• Corrija el script para que salga 0 dentro de 30 segundos e imprima un objeto JSON de valores de encabezado de cadena en stdout. Consulte requisitos del script.
• Si su organización implementa el script a través de configuración administrada, pida a quien la mantenga que lo corrija.

En modo no interactivo con -p, la misma falla aparece en stderr como otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error> en su lugar.

headersHelper no ejecutado

Claude Code conectó un servidor MCP con solo sus headers estáticos y omitió el headersHelper del servidor, porque el asistente es un comando de shell y la carpeta no tiene confianza guardada. Una carpeta obtiene confianza guardada cuando establece su entrada en ~/.claude.json a mano o, fuera de su directorio de inicio, cuando acepta el diálogo de confianza para ella en una sesión interactiva. Consulte Trust a folder before its headersHelper runs para ver a qué servidores se aplica esta verificación.

Claude Code escribe esta línea en modo no interactivo solo, una vez por servidor. En una sesión interactiva escribe el mismo rechazo en el registro de depuración en su lugar.

MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/Users/you/project"].hasTrustDialogAccepted in /Users/you/.claude.json.

La clave projects que imprime el mensaje es la carpeta en la que Project allow rules and workspace trust dice que Claude Code basa la confianza. Aceptar el diálogo de confianza para una carpeta padre no satisface la verificación, y una sesión -p o SDK tampoco la satisface.

Qué hacer:

• Ejecute claude en la carpeta que nombra el mensaje, acepte el diálogo de confianza, luego ejecute su comando -p o SDK de nuevo
• Establezca la entrada hasTrustDialogAccepted en ~/.claude.json usted mismo, usando la clave exacta projects que imprime el mensaje
• Si inició la sesión en su directorio de inicio, trabaje desde un directorio de proyecto en el que haya confiado. Cuando acepta el diálogo de confianza en su directorio de inicio, Claude Code mantiene esa confianza solo para la sesión actual.

Regla Tool(content) malformada

Una regla de permiso en uno de sus archivos de configuración no tiene la forma Tool o Tool(content), por ejemplo porque el texto sigue al paréntesis de cierre o falta uno de los paréntesis. Claude Code omite la regla y la enumera en el diálogo de configuración no válida cuando se inicia una sesión interactiva, y en la salida de claude doctor:

Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal

Qué hacer:

• En el archivo de configuración listado con el mensaje, reescriba la regla para que termine en su paréntesis de cierre, por ejemplo Bash(ls *) en lugar de Bash(ls) x
• Deje los paréntesis dentro del contenido como están. Son literales, por lo que una regla como Edit(./Finance (2024)/*) es válida sin escapar

Antes de v2.1.260, Claude Code reportaba una regla con paréntesis sin emparejar como Mismatched parentheses.

No coincide con las verificaciones de permiso de archivo

Claude Code encontró una regla de permiso Write, NotebookEdit, MultiEdit o Glob permission rule con una ruta en uno de sus archivos de configuración, en configuración administrada, o en un valor de bandera --allowedTools, --disallowedTools o --settings. Verifica permisos de archivo solo contra reglas Edit y Read, por lo que nunca consulta una regla de ruta que nombre una de las otras herramientas de archivo. Mantiene la regla y no cambia nada más; la advertencia nombra la regla, su fuente entre paréntesis, y el reemplazo a escribir:

Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

Qué hacer:

• Reemplace las reglas Write(path), NotebookEdit(path) y MultiEdit(path) heredadas con Edit(path). Las reglas Edit cubren todas las herramientas de edición de archivos.
• Excepto en --allowedTools, donde Claude Code acepta una regla Glob sin advertencia, reemplace las reglas Glob(path) con Read(path).
• Corrija la regla en la fuente que nombra la advertencia entre paréntesis: una ruta de archivo de configuración, o la bandera misma para --allowed-tools y --disallowed-tools. Una ruta claude-settings-<hash>.json que no existe en el disco representa un valor --settings en línea. Corrija el JSON que pasa a esa bandera.
• Deje las reglas de nombre de herramienta simple como Write o Glob solas. Claude Code las coincide en el nivel de herramienta y no advierte sobre ellas.
• Si la fuente dice managed policy settings, reenvíe la advertencia a quien mantenga su configuración administrada, ya que no puede borrarla usted mismo.

En una sesión en segundo plano o con --output-format json o stream-json, Claude Code escribe la advertencia en el registro de depuración en lugar de stderr, por lo que la salida leída por máquina se mantiene limpia. Ejecute con --debug para capturarla en ~/.claude/debug/<session-id>.txt. Antes de v2.1.210, Claude Code aceptaba estas reglas sin una advertencia.

Tiene un comodín antes del resto del comando

Claude Code encontró una regla de permiso Bash allow cuyo * viene antes de una palabra posterior que determina cuál es el comando, como Bash(git * main) o Bash(git -C * status *), en uno de sus archivos de configuración, en configuración administrada, o en un valor de bandera --allowedTools o --settings. El * coincide con cualquier texto, incluidas opciones insertadas en esa posición: Bash(git * main) también aprueba git -c core.fsmonitor=<script> diff main, donde -c hace que git ejecute un programa que nombra el comando. Wildcard patterns muestra las reglas de coincidencia.

La advertencia existe para que pueda estrechar una regla cuyo comodín es más amplio de lo que pretendía. Claude Code mantiene la regla y no cambia nada sobre cómo coincide; la advertencia nombra la regla y su fuente entre paréntesis:

Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).

Qué hacer:

• Reemplace el * antes del subcomando con el valor exacto que significa: Bash(git checkout main) en lugar de Bash(git * main).
• Mueva cada * después del subcomando: Bash(git status *) en lugar de Bash(git -C * status *). Escriba una regla por subcomando que desee permitir.
• Corrija la regla en la fuente que nombra la advertencia entre paréntesis: una ruta de archivo de configuración, o la bandera --allowed-tools misma. Una ruta claude-settings-<hash>.json que no existe en el disco representa un valor --settings en línea. Corrija el JSON que pasa a esa bandera.
• Si la fuente dice managed policy settings, reenvíe la advertencia a quien mantenga su configuración administrada, ya que no puede borrarla usted mismo.

En una sesión en segundo plano o con --output-format json o stream-json, Claude Code escribe la advertencia en el registro de depuración en lugar de stderr, por lo que la salida leída por máquina se mantiene limpia. Ejecute con --debug para capturarla en ~/.claude/debug/<session-id>.txt. Antes de v2.1.246, Claude Code aceptaba estas reglas sin una advertencia.

crossSessionInbound debe ser uno de accept, hold, refuse

Un archivo de configuración establece crossSessionInbound en un valor que Claude Code no reconoce, como el error tipográfico "reject". La segunda oración de la advertencia depende de qué archivo contiene el valor; en un archivo de usuario, proyecto, local o --settings dice:

"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.

En configuración administrada, Claude Code trata el valor no reconocido como refuse, el valor más restrictivo, y la advertencia dice que los mensajes entre sesiones se rechazan hasta que un administrador lo corrija. Para cómo la retención se combina con valores en sus otros archivos de configuración, consulte crossSessionInbound.

Qué hacer:

• Establezca la clave en "accept", "hold" o "refuse", o elimínela
• Cuando la advertencia nombra configuración administrada, pida al administrador que corrija el valor

Antes de v2.1.248, Claude Code ignoraba un valor no reconocido sin advertencia.

ANTHROPIC\_FOUNDRY\_RESOURCE debe ser un nombre de recurso de Foundry

Estableciste ANTHROPIC_FOUNDRY_RESOURCE en algo distinto de un nombre de recurso de Microsoft Foundry sin más, como la URL del endpoint o su nombre de host. Claude Code rechazó el valor antes de enviar una solicitud. El mensaje aparece en lugar de la respuesta de Claude, no como una advertencia de inicio:

API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name (2-64 letters, digits and hyphens, not starting or ending with a hyphen, such as my-resource), not a URL or host name. To use a full URL, set ANTHROPIC_FOUNDRY_BASE_URL instead.

Qué hacer:

• Establece ANTHROPIC_FOUNDRY_RESOURCE solo con el nombre del recurso y reinicia Claude Code. Para el endpoint https://my-resource.services.ai.azure.com/anthropic, el nombre es my-resource.
• Para indicar en su lugar la URL completa del endpoint, establece ANTHROPIC_FOUNDRY_BASE_URL con la URL y elimina ANTHROPIC_FOUNDRY_RESOURCE, luego reinicia Claude Code. Claude Code acepta solo una de las dos variables.

El límite de 200K no se aplica

Estableció CLAUDE_CODE_DISABLE_1M_CONTEXT=1, que normalmente hace que auto-compaction mantenga sesiones en modelos de contexto 1M en una ventana de 200K, pero ningún umbral de compactación limita esta sesión a o por debajo de 200K, por lo que la conversación puede crecer más allá.

CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).

Claude Code aplica el límite de 200K por su cuenta para cada modelo que reconoce como teniendo una ventana nativa de 1M, y para ID de modelo que no reconoce compacta en la ventana que asume. La advertencia aparece cuando otra configuración derrota esa aplicación:

• El ID del modelo no es uno que Claude Code reconozca, como un alias de LLM gateway, y estableció CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 o elevó la ventana asumida más allá de 200K con CLAUDE_CODE_MAX_CONTEXT_TOKENS. En este caso el mensaje también ofrece or update to a Claude Code version that recognizes <model> como un remedio.
• Un context-1m beta solicitado a través de ANTHROPIC_BETAS o la bandera --betas aún solicita a la API la ventana de 1M en un modelo que acepta esa beta, mientras que nada compacta la sesión a 200K

Qué hacer:

• Establezca CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000, o la configuración autoCompactWindow a 200000, para que auto-compaction compacte en el límite de 200K
• Si el mensaje nombra un ID de modelo que esta versión no reconoce, ejecute claude update. Una versión que reconoce el ID como un modelo de contexto 1M aplica el límite sin configuración adicional.
• Si desea que la sesión use la ventana completa del modelo en su lugar, desestablezca CLAUDE_CODE_DISABLE_1M_CONTEXT; la advertencia reporta solo que el límite de 200K no se aplica

En una sesión en segundo plano o con --output-format json o stream-json, Claude Code escribe la advertencia en el registro de depuración en lugar de stderr.

ID de modelo no reconocido en una solicitud

Claude Code envió una solicitud para un ID de modelo que su versión de Claude Code no reconoce, y no encontró ninguna entrada modelOverrides que asigne ese ID a un modelo que sí reconoce. Claude Code aún envía la solicitud con el ID como lo configuró, y no se cierra ni cambia de modelo.

[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

En un script o arnés que lee stderr, coincida con el prefijo [claude-code:unrecognized_model]. Después del prefijo y un espacio, Claude Code escribe un objeto JSON de una línea. Claude Code puede agregar campos a él en una versión posterior, así que ignore cualquier campo que no espere. Escribe al menos estos dos:

• model: la cadena del modelo como la configuró
• query_source: la ruta de solicitud que usó el modelo. Claude Code reporta sdk para una ejecución -p y un valor que comienza con agent: para un subagente.

Claude Code escribe la línea en uno de dos lugares, dependiendo de cómo la ejecute:

• En modo no interactivo con -p, Claude Code la escribe en stderr bajo cada --output-format, para que pueda analizar stdout sin filtrar la línea
• En una sesión interactiva o una sesión en segundo plano, Claude Code la escribe en el registro de depuración en su lugar; ejecute con --debug para capturarla en ~/.claude/debug/<session-id>.txt

Claude Code escribe la línea una vez por cadena de modelo por proceso. Escribe una línea separada para cada ID no reconocido adicional, como uno que un subagente o funcionalidad en segundo plano usa.

Claude Code no escribe la línea para ID de proveedor que resuelve a un modelo que reconoce, como ID de Amazon Bedrock us.anthropic.claude-..., ID de plataforma de agente de Google Cloud con un sufijo de versión @, y nombres de implementación de Microsoft Foundry que contienen un ID de modelo Claude. Claude Code verifica el modelo detrás de un ARN de perfil de inferencia de aplicación de Amazon Bedrock en lugar del ARN mismo. No escribe ninguna línea para un ARN que no puede resolver, como uno mal escrito.

Qué hacer:

• Si estableció el ID a propósito, como un alias de LLM gateway, agregue una entrada modelOverrides a su archivo de configuración con el ID como su valor. Use un ID de modelo Anthropic como la clave, no un alias de familia como opus. Para my-proxy-model de la línea de ejemplo, agregue esta entrada:

  {
    "modelOverrides": {
      "claude-opus-4-6": "my-proxy-model"
    }
  }
  

  Claude Code entonces trata my-proxy-model como claude-opus-4-6 y deja de escribir la línea.

• Si el ID nombra un modelo más nuevo que su versión de Claude Code, ejecute claude update

• Si el ID es un error tipográfico, corrígalo en cualquiera de los lugares donde puede establecer un modelo o variables de alias que lo contiene. Si query_source comienza con agent:, corrígalo donde establece el modelo del subagente en su lugar.

Antes de v2.1.233, Claude Code no escribía ninguna línea cuando enviaba una solicitud para un ID de modelo que no reconocía.

Archivos de máscara de sandbox obsoletos dejados por una sesión eliminada

claude doctor imprime esta advertencia en sus diagnósticos, y /status enumera la misma línea. Aparece en Linux y WSL2 cuando sandboxing está habilitado con aislamiento del sistema de archivos activado.

Mientras se ejecuta un comando en sandbox, el sandbox mantiene una negación de escritura en un archivo que aún no existe creando un marcador de posición de lectura de 0 bytes de solo lectura allí, y lo elimina después. Una sesión eliminada antes de que se ejecute esa limpieza, por ejemplo por SIGKILL, deja los marcadores de posición atrás. Las sesiones posteriores los vinculan de solo lectura de nuevo en cada inicio, por lo que una escritura de configuración como guardar "Sí, y no preguntar de nuevo" falla donde uno se sienta.

- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json
  Fix: Remove each with `rm <path>` while no other Claude Code session is running in that project — a 0-byte read-only file where a settings file belongs makes "Yes, and don't ask again" fail to save, and the sandbox binds it read-only again on every start

Qué hacer:

• Cierre cualquier otra sesión de Claude Code ejecutándose en ese proyecto, luego elimine cada archivo listado con rm. La advertencia nombra hasta tres archivos y cuenta el resto, así que reejecutar claude doctor después de eliminar hasta que la advertencia ya no aparezca. Un marcador de posición que el sandbox de otra sesión aún está usando es una parte viva de la protección de escritura de esa sesión
• Si una opción de permiso que guardó con "Sí, y no preguntar de nuevo" no se mantuvo, guárdela de nuevo después de eliminar el marcador de posición

Antes de v2.1.257, claude doctor no marcaba estos archivos; las versiones anteriores dejan los mismos marcadores de posición atrás cuando se elimina una sesión.

Las respuestas parecen de menor calidad que lo habitual

Si las respuestas de Claude parecen menos capaces de lo que espera pero no se muestra ningún error, la causa suele ser el estado de la conversación en lugar del modelo en sí. Claude Code no cambia silenciosamente las versiones del modelo. Puede cambiar a un modelo de respaldo en estos casos:

• Un --fallback-model configurado toma el control después de un error de disponibilidad, solo para ese turno, con un aviso en la transcripción
• Una verificación de inicio de Amazon Bedrock o de la plataforma de agentes de Google Cloud encuentra su modelo predeterminado no disponible, o su cuenta pierde acceso a él durante la sesión
• El respaldo automático de modelo en Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5 y Opus 5 mueve la sesión al modelo de respaldo de la categoría marcada, cuando esa categoría tiene uno, y muestra un aviso en la transcripción

La verificación de selección de modelo a continuación detecta el segundo y tercer caso; el primero aparece como un aviso de transcripción en lugar de un cambio de /model. La configuración del modelo explica cuándo se aplica cada respaldo.

Verifique estos primero:

• Selección de modelo: ejecute /model para confirmar que está en el modelo que espera. Una opción anterior de /model o una variable de entorno ANTHROPIC_MODEL pueden tenerlo en un modelo más pequeño del que pretendía.
• Nivel de esfuerzo: ejecute /effort para verificar el nivel de razonamiento actual y auméntelo para depuración difícil o trabajo de diseño. Los valores predeterminados varían según el modelo, así que verifique antes de asumir que está por debajo del máximo. Consulte Ajustar nivel de esfuerzo para los valores predeterminados por modelo y el atajo ultrathink.
• Presión de contexto: ejecute /context para ver qué tan llena está la ventana. Si está cerca de la capacidad, ejecute /compact en un punto natural o /clear para comenzar de nuevo. Consulte Explorar la ventana de contexto para ver cómo auto-compact afecta los turnos anteriores.
• Instrucciones obsoletas: los archivos CLAUDE.md grandes u obsoletos y las definiciones de herramientas MCP consumen contexto y pueden dirigir las respuestas. La verificación /doctor marca archivos de memoria de gran tamaño y extensiones no utilizadas, y /context muestra el uso de tokens de herramientas MCP. Antes de v2.1.205, /doctor abría una pantalla de diagnósticos que marcaba archivos de memoria de gran tamaño y definiciones de subagentes.

Cuando una respuesta sale mal, retroceder generalmente funciona mejor que responder con correcciones. Presione Esc dos veces o ejecute /rewind para retroceder antes del turno incorrecto, luego reformule el mensaje con más especificidades. Corregir en el hilo mantiene el intento incorrecto en contexto, lo que puede anclar respuestas posteriores a él. Consulte Checkpointing.

Si la calidad aún parece incorrecta después de verificar lo anterior, ejecute /feedback y describa qué esperaba versus qué obtuvo. La retroalimentación enviada de esta manera incluye la transcripción de la conversación, que es la forma más rápida para que Anthropic diagnostique una regresión real. Consulte Reportar un error si /feedback no está disponible en su entorno.

Si Claude advierte sobre una inyección de mensaje sospechosa, o rechaza una solicitud debido a una inyección sospechada, y el texto que nombra la advertencia es contexto que Claude Code agrega a la conversación automáticamente en lugar de contenido de archivo o web, ejecute claude update e intente de nuevo. Si la advertencia se repite después de actualizar, repórtela en lugar de pegar el contenido marcado nuevamente en el mensaje. Antes de v2.1.201, Sonnet 5 rechazaba algunas solicitudes de la misma manera.

Reportar un error

Para errores de componentes que esta página no cubre, consulte la guía relevante:

• El servidor MCP no se pudo conectar o autenticar: MCP
• El script de hook falló o bloqueó una herramienta: Depurar hooks
• Permiso denegado o errores del sistema de archivos durante la instalación: Solucionar problemas de instalación e inicio de sesión

Si un error no aparece aquí o la corrección sugerida no ayuda:

• Ejecute /feedback dentro de Claude Code para enviar la transcripción y una descripción a Anthropic. El comando también ofrece abrir un problema de GitHub rellenado previamente. El envío a Anthropic requiere autenticación. En Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry y otros proveedores de terceros, o cuando no hay credenciales de Anthropic configuradas, /feedback guarda un archivo local que puede enviar a su representante de cuenta de Anthropic en su lugar.
• Ejecute claude doctor desde su shell para un diagnóstico de solo lectura de su instalación, o ejecute la verificación /doctor dentro de Claude Code para encontrar y solucionar problemas de configuración
• Consulte status.claude.com para incidentes activos
• Busque problemas existentes en GitHub