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.
Claude Code llama a la API de Claude para respuestas del modelo, por lo que la mayoría de los errores en tiempo de ejecución se asignan a un código de error de API subyacente. Esta página cubre lo que cada error significa dentro de Claude Code y cómo recuperarte. Para las definiciones de código de estado HTTP sin procesar, consulta la referencia de errores de la plataforma Claude.
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 producedsi 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 diceYour 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 vuelve a enviar la solicitud en streaming como máximo una vez. 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. Al cumplirse el plazo, Claude Code aborta la solicitud y la reenvía dentro del presupuesto de reintentos. Si el plazo también se cumple para un reenvío, el turno termina con No response from API. Cuando estableces
CLAUDE_CODE_RETRY_WATCHDOG, Claude Code en su lugar sigue reenviándola dentro del presupuesto. - Una respuesta en streaming que el filtro de contenido de salida de la API detiene antes de que Claude haya terminado de pensar o haya comenzado cualquier texto o llamada a herramienta. Claude Code reenvía la solicitud una vez, dentro del presupuesto de reintentos, y muestra Output blocked by content filtering policy si el filtro también detiene la segunda respuesta.
- Limitaciones temporales 429, pero no el
429de 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_tokensexcede el límite de contexto. Reenviarla sin cambios fallaría de la misma manera, por lo que Claude Code reintenta con unmax_tokensreducido, 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_tokensmá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 respuesta que indica que Claude está llamando a una herramienta pero no contiene ninguna llamada a herramienta. Claude Code reintenta pidiéndole a Claude la llamada a herramienta, hasta dos veces. Si ambos reintentos fallan de la misma manera, ves
The model's tool call could not be parsed (retry also failed).y el turno termina. Para volver a intentarlo, envía otro mensaje. Antes de v2.1.307, Claude Code reintentaba una vez antes de terminar el turno. - 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
401o403de la API de Anthropic, directamente o a través de un gateway de LLM, mientras un scriptapiKeyHelpersuministra 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.
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_CERTSfaltante 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 regresivaRetrying 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.
Waiting for API response
El bannerWaiting for API response · will retry in … · check your network significa que Claude Code ha esperado al menos 20 segundos sin recibir ningún dato para una solicitud. La solicitud aún no ha fallado: la cuenta regresiva corre hasta el punto en que Claude Code aborta la conexión estancada. Si la conexión se aborta:
- 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 de espera aparece y desaparece detrás de un gateway
Si el bannerWaiting for API response aparece y desaparece mientras Claude piensa y te conectas a través de un gateway, actualiza Claude Code a v2.1.309 o posterior. El banner aparece después de 45 segundos sin datos en estas conexiones:
ANTHROPIC_BASE_URLestablecido en un host distinto de la API de Anthropic, como un gateway de LLM- Una sesión de Claude apps gateway
- Claude Platform on AWS con
ANTHROPIC_AWS_BASE_URLestablecido
Ajustar el comportamiento de reintentos
Puedes ajustar el comportamiento de reintentos con estas variables de entorno:Cuánto espera un intento sin streaming
Un intento sin streaming termina al agotarse su tiempo de espera de solicitud o su tiempo de espera de inactividad del cuerpo, lo que ocurra primero:- Tiempo de espera de solicitud:
API_TIMEOUT_MScuando estableces un valor positivo; de lo contrario, 300 segundos en una sesión local. - Tiempo de espera de inactividad del cuerpo: de 5 a 6 minutos sin respuesta, por alto que establezcas
API_TIMEOUT_MS, en los casos en que se aplica y no lo has desactivado.
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: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 againen lugar de pegarlo completo. - Si
ANTHROPIC_BASE_URLapunta a un gateway de LLM y todas las solicitudes fallan de esta manera, comprueba que tu gateway y su upstream acepten los campos de búsqueda de herramientas. Por defecto, Claude Code envía campos de herramientadefer_loadingy bloquestool_reference, con el encabezadoanthropic-betaque los habilita. Antes de v2.1.304, la búsqueda de herramientas estaba desactivada detrás de un gateway a menos que la activaras conENABLE_TOOL_SEARCH. - Si el error persiste sin ningún incidente publicado, ejecuta
/feedbackpara que Anthropic pueda investigar con los detalles de tu solicitud. Consulta Informar un error si/feedbackno 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:- 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
/modely 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 ejemploOpus 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 diceOpus 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.API_TIMEOUT_MS en 0, este tiempo de espera de la solicitud se desactiva. El plazo del primer byte y el tiempo de espera de inactividad del cuerpo no se desactivan cuando estableces 0, así que una solicitud en streaming sigue ejecutándose bajo los que se apliquen a tu conexión. Un intento sin streaming mantiene su límite de 300 segundos en una sesión local y aún puede terminar con este mensaje.
Qué hacer:
- Si todas las solicitudes fallan con este mensaje y estableciste
API_TIMEOUT_MSen0, compruebaclaude --version. En una versión anterior a v2.1.305, actualiza Claude Code o establece un valor positivo. - Reintenta la solicitud
- Si la causa es una red lenta o un proxy, aumenta
API_TIMEOUT_MScomo 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. Claude Code aborta una solicitud así en lugar de esperar el tiempo de espera completo de la solicitud,API_TIMEOUT_MS, y la envía de nuevo si el presupuesto de reintentos lo permite. Cuando el plazo también vence para el reintento, el turno termina con este mensaje, que muestra cuánto tiempo esperó cada intento.
Si estableces CLAUDE_CODE_RETRY_WATCHDOG, Claude Code sigue reintentando según el presupuesto descrito en Ajustar el comportamiento de los reintentos en lugar de terminar el turno.
-
Primer intento:
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MScuando 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. Excepto en Amazon Bedrock, si establecesAPI_TIMEOUT_MSen0, el reintento espera 10 minutos más un segundo por cada 32KB, o lo mismo que el primer intento si eso es más largo.
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.
En una sesión de Claude apps gateway, este plazo solo se aplica cuando lo activas estableciendo CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS en 1 o más.
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 againen 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_MSpara que el reintento espere más. En Amazon Bedrock, aumenta tambiénCLAUDE_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_MSpara que el primer intento también espere lo suficiente.
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. Antes de v2.1.307, Claude Code ignoraba CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS en una sesión de Claude apps gateway.
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: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 conAPI 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 conAPI 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 deANTHROPIC_BASE_URLoANTHROPIC_AWS_BASE_URLmientras 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 comoANTHROPIC_BEDROCK_BASE_URLno están cubiertos por el watchdog de bytes; consulta Watchdogs de inactividad del streaming.
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.oThe 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 conAPI Error: Content block not foundpara un evento perdido oAPI Error: Content block already closedpara uno duplicado. Para un evento dañado con el respaldo desactivado, el turno termina conAPI Error: Stream event unreadableo con el error sin procesar del analizador.
- 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 enviarcontinuetú 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.
- 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
continuepara 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
-py descartaba la respuesta que ya había producido. - Con
--output-format jsonostream-json, Claude Code informa este mensaje en el camporesult. - Para continuar el turno cuando la conexión sea estable, reanuda la sesión y envía
continuecomo se describe en Continuar conversaciones.
- 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
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. Cuando el modelo clasificador no está disponible:Not run · auto mode's check had no usable answer debajo de la llamada a herramienta en lugar de este mensaje. La fila también puede reemplazar un mensaje que indica que el servidor no dio ningún veredicto o, fuera de una sesión remota, uno que empieza con Auto mode could not evaluate. Presiona Ctrl+O para leer su mensaje en el visor de transcripciones. Antes de v2.1.296, el mensaje aparecía como un error en rojo.
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
- Si el mensaje reaparece en cada reintento y nombra el modelo que estableciste en
CLAUDE_CODE_AUTO_MODE_MODEL, comprueba que la API o el proveedor de nube en el que se ejecuta tu sesión ofrezca ese ID de modelo. Si no lo ofrece, establece la variable en un ID de modelo que sí ofrezca, o elimina la variable para usar el modelo clasificador predeterminado.
- Reintenta la acción; normalmente funciona en el siguiente intento
- Ejecuta
claude --debugy repite la acción para ver los detalles en el registro de depuración
-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
-psin--input-format stream-json, Claude Code le devuelve un resultado de error que contieneAgent 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
- 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
- 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
-psin--input-format stream-json, Claude Code le devuelve un resultado de error que contieneAgent 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
-psin--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
- En una sesión interactiva, aprueba o deniega la acción en la solicitud que aparece
- En una sesión interactiva, ejecuta
/compactpara 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):
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:
- 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
- En una sesión interactiva, presiona
Ctrl+Opara leer el texto de la denegación en el visor de transcripciones. - Si la denegación nombra
(the conversation is too long for the check), ejecuta/compacten el prompt de Claude Code para acortar la conversación. Hasta que la conversación sea más corta, enviar otro mensaje produce la misma denegación. Si desactivaste la compactación automática, vuelve a activarla para que Claude Code compacte por su cuenta la próxima vez. - 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=0antes 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
a hook changed this call's input after auto mode reviewed it
Esta denegación significa que un hook o mod cambió la entrada de la llamada después de que el servidor la revisó, así que la revisión no cubre lo que se ejecutaría. No es un juicio de que la acción sea insegura.
Las llamadas posteriores en la misma respuesta de Claude pueden denegarse con este motivo:
- Detener el cambio: desactiva el hook o mod que cambió la llamada o una llamada anterior en la misma respuesta de Claude, o pídele a tu administrador que lo desactive. Para buscar un hook, ejecuta
/hooksen el prompt de Claude Code. En una sesión de terminal, ejecuta/pluginpara ver los mods activos. - Aprobar la llamada tú mismo: cambia al modo Manual
Was not reviewed and did not run
Una denegaciónwas not reviewed and did not run significa que la conversación es demasiado larga para que el clasificador del modo automático verifique la acción, así que la acción no se ejecutó. Claude Code le devuelve este mensaje a Claude:
- Una denegación
gave no verdict (the conversation is too long for the check) - El mensaje
Auto mode classifier transcript exceeded context window
- Si la compactación que anuncia el mensaje tiene éxito, no necesitas hacer nada.
- Si ves cualquiera de esos dos mensajes, ejecuta
/compacten el prompt de Claude Code para acortar la conversación tú mismo. Si desactivaste la compactación automática, vuelve a activarla para que Claude Code compacte por su cuenta la próxima vez.
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.- 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
Límites de uso
La mayoría de los errores en esta sección significan que se alcanzó una cuota vinculada a tu cuenta o plan. Tres funcionan de manera diferente:Server is temporarily limiting requests es una limitación del lado del servidor no relacionada con la cuota de tu 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 una solicitud 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ás uno de estos mensajes:/model te 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 Esperar a que se reinicie un límite de uso 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 intensa, 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:
- Espera 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 el ajuste Continue automatically at usage limit de la CLI en
/configson independientes, así que desactiva cada uno por separado. - Para el límite de Opus o Sonnet, ejecuta
/modely cambia a un modelo fuera de esa familia para seguir trabajando. Cada modelo tiene su propia caché de prompts, por lo que la siguiente solicitud relee toda la conversación sin aciertos de caché; consulta Cambiar de modelo - Ejecuta
/usagepara ver los límites de tu plan y cuándo se reinician - Ejecuta
/usage-creditspara comprar uso adicional en Pro, Max y Ultra, o para solicitarlo a tu administrador en Team y Enterprise. Consulta créditos de uso para planes de pago para ver cómo se factura esto. - Para actualizar tu plan y obtener límites base más altos, consulta claude.com/pricing
You've used 85% of your session limit · resets 3:45pm. Para ver tu asignación restante de forma continua, agrega los campos rate_limits a una línea de estado personalizada, o en la aplicación de escritorio haz clic en el anillo de uso.
Usage credits required for 1M context
El modelo seleccionado utiliza la ventana de contexto extendida de 1M tokens, y tu plan solo la incluye a través de créditos de uso./compact; ejecuta /clear en esas versiones para recuperarte. Los pasos a continuación se aplican cuando seleccionaste explícitamente un modelo [1m].
Qué hacer:
- Ejecuta
/modely selecciona la variante sin el sufijo[1m]para volver a la ventana de contexto estándar - Donde el mensaje menciona
/usage-credits, ejecútalo para activar la facturación medida de la variante de 1M en Pro, Max y Ultra, o para solicitar créditos de uso a tu administrador en Team y Enterprise. Una vez que los créditos de uso estén activados, reinicia Claude Code o inicia una nueva sesión, según lo que indique el mensaje. Hasta entonces, la sesión permanece en el límite de contexto estándar. - Si el error persiste después de
/model, es posible que un ID de modelo de 1M esté configurado en otro lugar. Consulta Configurar tu modelo para ver las ubicaciones de configuración que debes verificar en orden de prioridad. - Para eliminar por completo las variantes de 1M del selector de modelo, establece
CLAUDE_CODE_DISABLE_1M_CONTEXT=1
run /usage-credits to turn them on, or /model to switch to standard context y no mencionaba reiniciar.
The prompt to confirm went unanswered
Cuando la solicitud de consentimiento de créditos de uso de Fable se cierra sin que nadie la responda, Claude Code termina el turno con uno de estos mensajes:continuing on Fable 5.2 y Fable 5.2 now uses usage credits. Con Remote Control conectado, cada mensaje puede terminar en cambio con Claude stopped here · send a message to be asked again, or switch models. Antes de v2.1.257, el primer mensaje comenzaba con Fable 5 limit reached.
Esto sucede en sesiones de Remote Control, sesiones en segundo plano, sesiones de compañeros de un equipo de agentes y sesiones que otra aplicación aloja a través del Agent SDK. Para saber cuándo Claude Code cierra la solicitud, consulta Fable y créditos de uso.
Qué hacer:
- Donde se ejecuta la sesión, en la terminal o en la aplicación que la aloja, envía otro prompt y responde la solicitud de consentimiento cuando vuelva a aparecer. Para una sesión en segundo plano, primero conéctate a ella desde la vista de agentes. Si el mensaje dice
Claude stopped here, también puedes responder desde tu dispositivo conectado y contestar la solicitud de consentimiento allí. - Ejecuta
/modelpara cambiar a un modelo que no facture créditos de uso - Para darte más tiempo, establece
dialogExpiryen un valor más largo o en"never"
Server is temporarily limiting requests
La API aplicó una limitación de corta duración que no está relacionada con la cuota de tu plan.- Espera un momento e inténtalo de nuevo
- Consulta status.claude.com si persiste
Request rejected (429)
Alcanzaste el rate limit configurado para tu clave de API, tu proyecto de Amazon Bedrock o tu proyecto de Google Cloud.ANTHROPIC_BASE_URL personalizado nombra el host del gateway.
Cuando un proxy, un balanceador de carga o un gateway 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 lo tiene, como Too Many Requests. Antes de v2.1.281, se imprimía todo el marcado de la página después del ·.
Qué hacer:
- Ejecuta
/statusy confirma que la credencial activa es la que esperas. UnANTHROPIC_API_KEYolvidado en tu entorno puede enrutar las solicitudes a través de una clave de nivel bajo en lugar de tu suscripción. - Consulta la consola de tu proveedor para ver los límites activos y solicita un nivel más alto si es necesario
- Para claves de API de Anthropic, consulta la referencia de rate limits para ver cómo funcionan los niveles y cómo establecer límites por espacio de trabajo
- Reduce la concurrencia: evita ejecutar muchos subagentes en paralelo o cambia a un modelo más pequeño con
/modelpara ejecuciones con scripts de alto volumen
You’ve hit your monthly spend limit
El uso incluido en tu plan no puede cubrir esta solicitud, y los créditos de uso que de otro modo la pagarían alcanzaron un límite de gasto. Tu plan no puede cubrir una solicitud cuando se agotó una de sus ventanas de uso, o cuando solo los créditos de uso pagan la solicitud. Un ejemplo es una solicitud a un modelo que se factura con créditos de uso. Las palabras antes del· nombran el límite que te bloqueó, como el límite de gasto mensual de tu organización, y el texto después dice cómo conseguir que se aumente ese límite. En una sesión en la nube o con Remote Control, ese texto no incluye ninguna URL, y un mensaje sobre tu propio monthly spend limit no dice cómo aumentarlo. Otras sesiones muestran formas como estas:
team's shared budget es un presupuesto compartido que un administrador asignó a un grupo al que perteneces; el mensaje no nombra el grupo. channel's monthly spend limit es el presupuesto del canal de Slack específico en el que se ejecuta la sesión, por lo que tu organización aún puede tener presupuesto fuera de él.
Cuando lo que se agotó es una de las ventanas de tu plan, el mensaje también dice cuándo se reinicia esa ventana, por ejemplo · your session limit resets 3:45pm, y el acceso vuelve en ese momento 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.
Si te conectas a través de un gateway de aplicaciones Claude y ves spend limit reached en minúsculas, se trata en cambio del límite del operador de tu gateway; consulta Spend limit reached.
Qué hacer:
- En Pro, Max y Ultra, aumenta tu límite de gasto mensual en Settings > Usage en claude.ai, o ejecuta
/usage-credits - En Team y Enterprise, aumenta el límite en Organization settings > Usage si gestionas la facturación, o pídele a un administrador que lo haga.
/usage-creditsenvía esa solicitud a tu administrador por ti - Para el límite de un canal, pide a un propietario de la organización o al administrador del canal que lo aumente en claude.ai. Consulta Per-channel limits en la documentación de Claude Tag
- Si el mensaje indica una hora de reinicio para la ventana de tu plan, puedes esperar a que llegue
- Ejecuta
/usagepara ver las ventanas de tu plan y cuándo se reinicia cada una
Spend limit reached
Te conectas a través de un gateway de aplicaciones Claude y alcanzaste un límite de gasto que estableció el operador de tu gateway. El gateway bloquea tus solicitudes hasta que el operador aumente el límite, o hasta que el límite se reinicie si es superior a $0. Marca cada respuesta429 bloqueada con x-should-retry: false, por lo que en la terminal Claude Code muestra este mensaje sin reintentar.
- Con una fecha: el límite se reinicia a las 00:00 UTC de esa fecha
- Sin fecha: tu límite es de $0, o tu gateway ejecuta una versión anterior a v2.1.225
spend limit reached (daily; resets 2026-08-09 00:00 UTC).
Qué hacer:
- Si el mensaje tiene una fecha, espera el reinicio, o sigue la nota del operador si el mensaje la incluye
- Pide al operador de tu gateway que aumente el límite si el mensaje no tiene fecha, si sigues bloqueado después de la fecha o si alcanzas el límite con frecuencia
This request exceeds your group's budget, significa que el presupuesto compartido de tu grupo se agotó. Sigue los pasos que indica:
spend limit unavailable, significa que el gateway no pudo leer sus registros de gasto y bloqueó la solicitud como precaución, no porque superaras tu límite. Por lo general se resuelve solo; si persiste, avisa al operador de tu gateway.
Credit balance is too low
Tu organización de Console se quedó sin créditos prepagados, o Claude Code está enviando tus solicitudes con una clave de API de Console cuando querías usar tu suscripción.- Si tienes un plan Pro, Max, Ultra, Team o Enterprise y ves esto, ejecuta
/statusy revisa la filaAPI key. UnANTHROPIC_API_KEYaprobado en tu entorno enruta las solicitudes a través de esa clave en lugar de tu suscripción. Elimina la variable en el shell actual y quítala de tu perfil de shell, luego vuelve a iniciarclaude. Ejecuta/loginsi aún no iniciaste sesión con tu suscripción. - Agrega créditos en platform.claude.com/settings/billing, y considera activar ahí la recarga automática para que el saldo se recargue antes de llegar a cero
- Establece límites de gasto por espacio de trabajo en la Console para evitar que un solo proyecto agote el saldo de la organización. Consulta Administrar los costos de forma eficaz.
Could not update your spend limit
El servidor rechazó un cambio de límite de gasto que hiciste desde la solicitud que aparece cuando alcanzas tu límite de gasto.Could not update your spend limit. Press Enter to retry. y reintentar puede funcionar. Antes de v2.1.216, Claude Code mostraba la forma genérica para todos los fallos.
Si eliminas el límite, en v2.1.327 o posterior la forma genérica comienza con Could not remove your spend limit.
Qué hacer:
- Si el mensaje incluye una razón, elige un límite que la cumpla, como una cantidad menor
- Si el mensaje muestra solo la forma genérica, reintenta; el fallo puede ser transitorio
- Si el cambio sigue fallando, hazlo en cambio desde tu configuración de facturación de claude.ai en el navegador
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.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
/loginpara 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_KEYestá definida y exportada en el shell desde el que iniciasteclaude - Para CI o automatización donde el inicio de sesión interactivo no es posible, configura un script
apiKeyHelperque obtenga una clave al inicio - Si los trabajos de
claude -pterminan con este mensaje cuando alguien vuelve a iniciar sesión en la misma cuenta y organización de claude.ai, actualiza Claude Code donde se ejecuta ese inicio de sesión. Antes de la v2.1.318, Claude Code eliminaba el inicio de sesión almacenado durante ese inicio de sesión, antes de guardar el nuevo. - Consulta Precedencia de autenticación para entender qué credencial usa Claude Code cuando hay varias presentes
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.
- 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_TOKENo 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
/statusen 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 entornoANTHROPIC_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.
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 PowerShellGet-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.envde tu proyecto sin que la definas explícitamente. - Elimina
ANTHROPIC_API_KEYy ejecuta/loginpara 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
/statuspara confirmar qué fuente de credenciales está usando realmente Claude Code
Tu script apiKeyHelper está fallando
Claude Code ejecutó el comando de tu ajusteapiKeyHelper 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 keye 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.
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
apiKeyHelperpara 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
/statuspara ver el fallo y confirmar queapiKeyHelperes la fuente de credenciales activa. La filaapiKeyHelpermuestraFailingcon 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,/statusmostraba 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
Authenticationen la terminal. Antes de la v2.1.212, el panel se titulabaCloud authentication.
Claude Code didn’t send your claude.ai login
Estos mensajes significan que Claude Code rechazó tu solicitud y no envió tu inicio de sesión de claude.ai:Your organization's settings need an update: pide a tu administrador que corrija la configuración del helper de claves de API- Para indicarle a tu administrador qué fuentes administradas tiene tu máquina, ejecuta
/statusen el prompt de Claude Code y copia la líneaSetting sources. Si aparece una líneaSkipped sources, cópiala también - Si administras la configuración y el helper está en el archivo de configuración administrada de una máquina o en una política de MDM, consulta Cuando el
apiKeyHelperde una máquina no está en vigor
- Para indicarle a tu administrador qué fuentes administradas tiene tu máquina, ejecuta
Couldn't load your organization's settings: revisa tu conexión y luego reinicia Claude Code. Si el mensaje vuelve a aparecer después de reiniciar, avisa a tu administradorRestart Claude Code to finish signing in: reinicia Claude Code
Claude Code didn't send your claude.ai login.
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 deU+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: un token bearer deANTHROPIC_AUTH_TOKENoCLAUDE_CODE_OAUTH_TOKENInvalid ANTHROPIC_CUSTOM_HEADERS: un nombre o valor de encabezado que definiste enANTHROPIC_CUSTOM_HEADERS. La descripción indica por número qué parName: Valuees el problemático, comodistinct 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, comoCLAUDE_AGENT_SDK_CLIENT_APP. La descripción indica la variable que debes corregir.
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:
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 parName: Valuepor línea y reescribe el par que indica el mensaje - Ejecuta
/statuspara confirmar qué fuente de credenciales está activa
Esta organización ha sido deshabilitada
Claude Code está usando unANTHROPIC_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.
· 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.
Si exportas una clave en el perfil de tu shell o la cargas desde .env, Claude Code la usa en lugar de /login, incluso con una suscripción Pro, Max o Ultra que funcione. En modo no interactivo (-p), la clave siempre se usa cuando está presente.
Qué hacer:
- Elimina
ANTHROPIC_API_KEYen el shell actual y quítala de tu perfil de shell; luego vuelve a iniciarclaude - 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
/statusdespué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:
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 iniciarclaude - Si el mensaje menciona
apiKeyHelper, quita el ajusteapiKeyHelperde tusettings.json - Ejecuta
/loginpara iniciar sesión con tu cuenta de claude.ai - Ejecuta
/statusdespué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.
-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
Scheduled tasks are off for your organization
Las tareas programadas en la nube están desactivadas para tu organización, así que no puedes crearlas ni ejecutarlas. El mensaje de claude.ai las llama tareas programadas o rutinas, y le sigue una frase sobre tu administrador:- Pregunta al Owner de tu plan Team o Enterprise si puede activar el interruptor con la etiqueta Scheduled tasks (Was Routines) o Routines en Organization settings > Capabilities > Remote sessions
Remote Control requiere la API de Anthropic
La sesión no se comunica directamente con la API de Anthropic, algo que Remote Control requiere.- Una variable de proveedor
CLAUDE_CODE_USE_*, comoCLAUDE_CODE_USE_BEDROCKpara Amazon Bedrock oCLAUDE_CODE_USE_VERTEXpara Agent Platform de Google Cloud ANTHROPIC_BASE_URLapuntando a un host distinto deapi.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 ControlANTHROPIC_UNIX_SOCKETdefinida, de modo que la sesión envía sus solicitudes a través de un socket local en lugar de aapi.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
- Elimina la variable que menciona el mensaje, como
CLAUDE_CODE_USE_BEDROCKoANTHROPIC_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
enven 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 informaOAuth 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:
Claude.ai login expiredyClaude.ai login was rejected: claude.ai ya no acepta tu token de inicio de sesión guardado, porque expiró o fue revocadoOAuth 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ónOAuth 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 nuevoJWT refresh failed: no OAuth token: Claude Code no encontró ningún token de inicio de sesión guardado con el que renovarSigned out of Claude: cerraste sesión en esta máquina, por ejemplo ejecutando/logouten otra terminal, así que Claude Code no tiene ningún inicio de sesión guardado con el que renovar la conexión
- Ejecuta
/loginpara volver a iniciar sesión - Ejecuta
/remote-controlpara reconectar la sesión. Los mensajes que terminan enrun /login to restore Remote Controlno necesitan este paso: Claude Code se reconecta por sí solo una vez que inicias sesión.
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 could not renew this computer’s connection
Esta advertencia aparece en la terminal que ejecutaclaude remote-control cuando el servidor no puede usar tu inicio de sesión de claude.ai para renovar la credencial de su conexión antes de que caduque. La última oración de la advertencia indica cuánto tiempo sigue funcionando la credencial actual, o que ya caducó:
- Si la advertencia te indica que ejecutes
claude /login, abre otra terminal en la máquina que ejecuta el servidor, ejecutaclaude /loginallí e inicia sesión con tu cuenta de claude.ai - Si el servidor sigue sin poder iniciar sesión una vez que la credencial de la conexión caducó, imprime un error que contiene
Poll: Authentication failed (401)y se detiene. Vuelve a iniciar sesión como indica la segunda oración de la advertencia y luego ejecuta de nuevoclaude remote-controlen la terminal donde se detuvo el servidor.
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.
- Ejecuta
/remote-controlpara iniciar una nueva sesión de Remote Control con la cuenta u organización actual - Para volver a la anterior, ejecuta
/logine inicia sesión de nuevo en la cuenta u organización anterior. Luego ejecuta/remote-control.
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:
- 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.
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. Si el inicio de sesión guardado ya se borró tras una actualización fallida, consulta Login expired en su lugar. Si te autenticas con un token de larga duración enCLAUDE_CODE_OAUTH_TOKEN, ves los mismos mensajes cuando ese token expira o es revocado.
-p) y en el Agent SDK, los mensajes dicen lo siguiente, y el código de error estructurado es authentication_failed:
Your account does not have access to Claude. Please login again or contact your administrator.
Qué hacer:
- Ejecuta
/loginen el prompt de Claude Code para volver a iniciar sesión - Si tu comando
-po tu programa del Agent SDK usa un inicio de sesión guardado, ejecutaclaudeen el mismo entorno, completa/loginy luego vuelve a ejecutar el comando o el programa. Para automatización que no puede iniciar sesión de forma interactiva, autentícate conANTHROPIC_API_KEYo genera un token de larga duración conclaude 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./statusmuestra esta credencial como una filaAuth tokenque diceCLAUDE_CODE_OAUTH_TOKEN. Genera un token nuevo conclaude setup-tokeny 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 Forbiddeny 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 unANTHROPIC_API_KEY aprobado, y la solución es distinta en cada caso, así que empieza ejecutando /status para ver cuál está activa.
- Si
/statusmuestra una filaAPI keyque no está marcada como no en uso, unANTHROPIC_API_KEYaprobado es la credencial activa y tiene precedencia sobre tu inicio de sesión, así que/loginno lo reemplaza. Rota la clave en Claude Console, o vuelve a tu suscripción ejecutandounset ANTHROPIC_API_KEY, o en PowerShellRemove-Item Env:ANTHROPIC_API_KEY. - Si
/statusmuestra solo tu inicio de sesión, ejecuta/loginuna 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_URLapunta a un gateway de LLM, el texto después de401es el mensaje de tu gateway y no el de Anthropic, y/loginno lo cambia. Corrige en su lugar la credencial que espera tu gateway. - Si todas las solicitudes fallan con un
401una vez que tu gateway tiene la credencial que espera, comprueba que el gateway y su upstream acepten los campos de búsqueda de herramientas. De forma predeterminada, Claude Code envía campos de herramientadefer_loadingy bloquestool_reference, con el encabezadoanthropic-betaque los habilita. Antes de la v2.1.304, la búsqueda de herramientas estaba desactivada detrás de un gateway a menos que la activaras conENABLE_TOOL_SEARCH.
Inicio de sesión expirado
Claude Code intentó renovar tu inicio de sesión de claude.ai guardado y el servicio OAuth rechazó el token de actualización almacenado, así que Claude Code borró las credenciales guardadas. Sin otra credencial guardada, las solicitudes al modelo se detienen entonces con este mensaje:-p) y en el Agent SDK, el mensaje dice lo siguiente, y el código de error estructurado es authentication_failed:
reached its time limit en Claude Code v2.1.318 o posterior. Para un mensaje Login expired que termina con or re-authenticate your Anthropic profile, consulta Anthropic profile login expired.
Cuando la renovación falla porque la propia cuenta está suspendida, Claude Code muestra en su lugar Your account is on hold.
Qué hacer:
- Ejecuta
/loginpara volver a iniciar sesión. - 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
claudeen el mismo entorno, completa/loginy luego vuelve a ejecutar tu comando. Para automatización que no puede iniciar sesión de forma interactiva, autentícate conANTHROPIC_API_KEYo genera un token de larga duración conclaude 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:-p) y en el Agent SDK, el mensaje dice lo siguiente, y el código de error estructurado es server_error:
- 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.
Could not refresh your login: the disk that holds the Claude Code config directory is full
Libera espacio en el disco que contiene el directorio de configuración de Claude Code y luego vuelve a enviar tu mensaje. Volver a iniciar sesión no ayudaría mientras el disco esté lleno, porque no se podría guardar un inicio de sesión nuevo. El directorio de configuración es~/.claude en tu directorio home, a menos que definas CLAUDE_CONFIG_DIR.
-p) y en el Agent SDK, el mensaje dice:
- En el caso de un script, vuelve a ejecutar su comando
claude -p - Si el disco ya muestra espacio libre, quedarse sin cuota de disco o sin inodos produce el mismo mensaje. Elimina tus propios archivos de ese disco. Si el mensaje vuelve a aparecer, elimina muchos archivos pequeños en lugar de unos pocos grandes, porque cada archivo ocupa un inodo sin importar su tamaño.
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.- 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
Sign in again to take your previous account or API key off the config file
Esta advertencia después de iniciar sesión significa que cualquier cuenta con la que tuvieras la sesión iniciada antes puede seguir almacenada en~/.claude.json:
~/.claude.json si un inicio de sesión de Console creó una en Linux o Windows.
Qué hacer:
- Ejecuta
claude auth loginen tu shell para volver a iniciar sesión. Claude Code reintenta entonces el guardado que quita del archivo la cuenta o la clave de API reemplazada.
Your account or API key may still be in the config file
Ejecutaste/logout o claude auth logout, y Claude Code cerró la sesión de este proceso, pero no pudo confirmar que ~/.claude.json ya no contenga tu cuenta. O el guardado no se aplicó, o el archivo no se pudo volver a leer para comprobarlo.
~/.claude.json si un inicio de sesión de Console creó una en Linux o Windows.
Qué hacer:
- Ejecuta
claude auth logouten tu shell para volver a intentar el guardado. Cuando el guardado se completa, el comando imprimeSuccessfully logged out from your Anthropic account.
Couldn’t start the local listener that receives the browser sign-in
Cada uno de estos mensajes de/login, claude auth login o claude setup-token significa que Claude Code no pudo abrir el puerto en 127.0.0.1 donde tu navegador devuelve el resultado del inicio de sesión.
Con el aviso que empieza con The browser can't return the sign-in to Claude Code automatically, el inicio de sesión continúa sin ese puerto. No se abre ningún navegador, y el aviso aparece encima de una URL donde inicias sesión en su lugar:
Couldn't start the local listener, el inicio de sesión se detuvo. Eso ocurre, por ejemplo, cuando canalizas una entrada hacia claude auth login:
The browser can't return the sign-in to Claude Code automatically: no necesitas corregir nada primero. Abre en un navegador la URL que aparece debajo del aviso e inicia sesión. Luego el navegador muestra un código: pégalo en Claude Code en el promptPaste code here >, y el inicio de sesión continúa desde ahí.Couldn't start the local listener that receives the browser sign-in: ejecuta el mismo comando de nuevo. Si se detiene de la misma manera, inicia sesión con un token o una clave de API en lugar del navegador. O, si canalizaste una entrada haciaclaude auth login, ejecútalo en una terminal para que pueda aceptar un código pegado.- Para iniciar sesión con un token o una clave de API en lugar del navegador: si usas una suscripción de claude.ai, ejecuta
claude setup-tokenen una máquina donde el inicio de sesión funcione. Luego define el token que imprime como la variable de entornoCLAUDE_CODE_OAUTH_TOKENen esta máquina. De lo contrario, define la variable de entornoANTHROPIC_API_KEYcon una clave de la Claude Console. Precedencia de autenticación explica cómo elige Claude Code entre credenciales. - Para recuperar el regreso automático desde el navegador: 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 iniciar sesión. Si escuchar debería funcionar ahí y el aviso sigue apareciendo, ejecuta/feedbackpara que el informe incluya los detalles de tu entorno.
Failed to start OAuth callback server: Failed to start server. Is port 0 in use?. En esas versiones, actualiza Claude Code y vuelve a iniciar sesión, o inicia sesión con un token o una clave de API en lugar del navegador.
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:- 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:- Ejecuta
/loginy 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 ajusteapiKeyHelpero una clave de Console guardada por un/loginanterior, 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 estableceforceLoginMethod 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:
/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:
- Para
Not signed in to the Cloud gateway, ejecuta/loginy 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
forceLoginMethodyforceLoginGatewayUrlde su configuración administrada
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:-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
/logincon esa cuenta, o define la clave conANTHROPIC_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.- Si el mensaje empieza por
Login expired, ejecuta/loginpara volver a iniciar sesión - Para renovar un perfil que escribió el inicio de sesión sin clave de Console o el
ant auth loginde la CLI de Claude Platform, ejecuta/loginen una máquina que ofrezca el inicio de sesión sin clave. Elige la cuenta de Anthropic Console y luego Sign in with your Console account. Claude Code reemplaza la credencial expirada en ese perfil - Para renovar un perfil que creó otra herramienta, vuelve a iniciar sesión con esa herramienta. Si en su lugar eliges Sign in with your Console account en
/login, Claude Code deja el perfil como está y crea una clave de API - Si un administrador aprovisionó la credencial del perfil, pídele que emita una nueva
- Ejecuta
/statuspara confirmar la fuente de credenciales activa y el nombre del perfil - Para dejar de usar el perfil, elimina
ANTHROPIC_PROFILEsi la definiste y luego autentícate de otra forma, como/loginoANTHROPIC_API_KEY
- Cuando Claude Code descubrió el perfil desde tu directorio de configuración y su modo de autenticación es
user_oauth, el mensaje empieza porLogin expiredy ofrece/loginprimero. Claude Code da a un/loginque funcione precedencia sobre el perfil descubierto y luego se autentica con tu cuenta de claude.ai en su lugar. Desde v2.1.234 hasta v2.1.277, esta forma decíaAnthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile. Antes de v2.1.234, Claude Code también mostraba la formaRe-authenticate your Anthropic profileen este caso. - Cuando seleccionaste el perfil con
ANTHROPIC_PROFILE, el mensaje empieza porAnthropic profile login expired.
ANTHROPIC_PROFILE, uno que Claude Code descubre como el perfil activo en tu directorio de configuración de Anthropic, o uno 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.
Requisito de alcance de OAuth
El token almacenado es anterior a un alcance de permisos que necesita una función más reciente:- Ejecuta
/loginpara 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:
- Ejecuta
/loginpara 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/mcpinformayour claude.ai session token was rejected; la forma escrita/mcp reconnect <server>informa una reconexión correcta aunque el token siga rechazado.
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, 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, lo que vuelve a ejecutar el helper.
Para un servidor con un encabezado Authorization estático en su configuración:
/mcp.
En una sesión de Cowork en tu máquina en la aplicación Claude Desktop, estos mensajes significan que el servidor MCP rechazó una credencial que se le proporcionó. Corrige la que indica el mensaje y luego inicia una nueva tarea o chat en Cowork:
- Credencial de
headersHelperrechazada: comprueba que el helper devuelva una credencial que el servidor acepte y luego inicia una nueva tarea o chat en Cowork - Encabezado
Authorizationrechazado: actualiza el valor deAuthorizationbajoheadersen la configuración de ese servidor y luego inicia una nueva tarea o chat en Cowork
run /mcp to reconnect, aunque /mcp no está disponible allí. Si ves uno de esos finales en Cowork, igualmente revisa el helper o actualiza el encabezado y luego inicia una nueva tarea o chat. Antes de la v2.1.273, los casos de inicio de sesión caducado, 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, 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.
Couldn’t read the stored credentials for MCP server
Claude Code guarda tus inicios de sesión de servidores MCP con OAuth en un almacén de credenciales. Este mensaje significa que Claude Code no pudo leer ese almacén, por lo que una solicitud al servidor no se ejecutó:claude -p o del Agent SDK en macOS, el llavero puede volverse legible después de que una solicitud ya se haya enviado sin el inicio de sesión almacenado. Esa solicitud falla con:
-
Si el mensaje te pide desbloquear el llavero de tu Mac, ejecuta
claude doctoren la sesión de shell desde la que ejecutas Claude Code y revisa su informe en busca de una advertencia sobre el llavero:-
Si el informe incluye una advertencia que empieza con
macOS Keychain is not writable, o tu shell no tiene el comandoclaude, ejecuta este comando de desbloqueo en esa sesión de shell: - Si el informe no incluye ninguna advertencia sobre el llavero, omite el comando de desbloqueo
-
Si el informe incluye una advertencia que empieza con
-
Vuelve a intentarlo donde viste el mensaje:
- Para
claude -p, ejecuta el comando de nuevo - En una sesión interactiva, reconecta el servidor desde
/mcpsi aparece como fallido allí y luego pide a Claude que lo intente de nuevo - En una aplicación del Agent SDK que sigue en ejecución, llama a
reconnectMcpServer()en TypeScript o aClaudeSDKClient.reconnect_mcp_server()en Python, o inicia una nueva sesión
- Para
-
Si el servidor informa entonces que necesita autenticación, Claude Code no encontró ningún inicio de sesión que pueda usar para ese servidor. Inicia sesión de forma interactiva: ejecuta
/mcpen una sesión de Claude Code, oclaude mcp login <name>en tu shell. En una aplicación del Agent SDK, consulta Autenticación OAuth2 en el Agent SDK.
claude -p o del Agent SDK en un Mac con el llavero de inicio de sesión bloqueado informaba que el servidor necesitaba autenticación en lugar de mostrar cualquiera de los dos mensajes.
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 laurl 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í:
- Establece la
urlde 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ámetroiss 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:
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
issel 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
MCP_SDK_GENERATION=v2.
Stopped an OAuth request
Este mensaje significa que Claude Code detuvo una solicitud OAuth para un servidor MCP porque un endpoint OAuth la redirigió. En ambas formas del mensaje, la primera dirección es la que envió la redirección:- Pide a quien administre la primera dirección, como el operador del servidor MCP, que elimine o corrija la redirección. Luego vuelve a intentarlo desde
/mcp.
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 enlocalhost, 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:
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 elAWS credentials expired or invalid inicial:
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
awsAuthRefreshestá definido, ejecuta en otra terminal el comando que indica el mensaje, comoaws 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
awsAuthRefreshdefinido 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-identityen 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 unAccessDeniedException 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 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
awsAuthRefreshque 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-identitypara 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 elGoogle Cloud credentials expired or invalid inicial:
- 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 estableciste
CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD, sigue en cambio los pasos de Claude Models on Google Cloud (administrado por Anthropic) - Si te autenticas con las credenciales predeterminadas de la aplicación, ejecuta el comando
gcpAuthRefreshque indica el mensaje, ogcloud 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_AUTHdefinida, renueva el token del gateway enANTHROPIC_AUTH_TOKENoANTHROPIC_CUSTOM_HEADERSy luego reintenta - Si te autenticas con un archivo de clave de cuenta de servicio, confirma que
GOOGLE_APPLICATION_CREDENTIALSapunta 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-tokenen el mismo shell
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 elGoogle Cloud authentication failed inicial:
- 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
- Si estableciste
CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD, sigue en cambio los pasos de Claude Models on Google Cloud (administrado por Anthropic) - 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
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:
- 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 unANTHROPIC_FOUNDRY_AUTH_TOKENnuevo o ejecutaaz loginpara 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
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. 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:
-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 myprofileogcloud 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.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-identityen el mismo shell con el mismoAWS_PROFILE. Si también se cuelga, corrige el perfil; un comandocredential_processque 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 conCLAUDE_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: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:
unreachable en lugar de mostrar cualquiera de los dos mensajes.
Qué hacer:
- Ejecuta
aws sts get-caller-identityen 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 iniciarclaude de forma interactiva, la sesión se abrió sin haber iniciado sesión en el gateway:
claude distinto de claude auth, Claude Code termina con este mensaje en su lugar cuando el gateway ya no acepta la sesión:
- Ejecuta
/loginen la sesión y completa el inicio de sesión en el navegador - Para un inicio no interactivo, inicia
claudeen el mismo entorno, ejecuta/loginy 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:- Ejecuta
/loginde 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:- 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
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 que 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 tu red local, proxy o firewall, o en la política de red del entorno en la nube.Unable to connect to API
La conexión TCP a la API falló o nunca se completó. Para los códigos de error de conexión comunes, el mensaje indica el tipo de fallo y mantiene el código entre paréntesis: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 con código decí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:
- Confirma que puedes alcanzar el host de la API desde el mismo shell ejecutando
curl -I https://api.anthropic.com. En Windows PowerShell usacurl.exe -I https://api.anthropic.compara que no se use el alias integradoInvoke-WebRequest. - Si estás detrás de un proxy corporativo, establece
HTTPS_PROXYantes de iniciar Claude Code y consulta Configuración de red - Si enrutas a través de un gateway LLM o un relé, establece
ANTHROPIC_BASE_URLen su dirección. Consulta Conectar Claude Code a un gateway LLM para la configuración. - Si
ANTHROPIC_BASE_URLya apunta a tu gateway y cada solicitud termina enConnection dropped, verifica que tu gateway y su servicio upstream acepten los campos de búsqueda de herramientas. De forma predeterminada, Claude Code envía campos de herramientasdefer_loadingy bloquestool_reference, junto con el encabezadoanthropic-betaque los habilita. Antes de v2.1.304, la búsqueda de herramientas estaba desactivada detrás de un gateway a menos que la activaras conENABLE_TOOL_SEARCH. - Asegúrate de que tu firewall permita los hosts enumerados en Requisitos de acceso a la red
- Los fallos intermitentes se reintentan automáticamente
curl tiene éxito pero Claude Code sigue fallando, la causa suele ser algo entre el runtime y la red, no la red en sí:
- Verifica si
ANTHROPIC_BASE_URLestá establecida ejecutandoecho $ANTHROPIC_BASE_URL, oecho $env:ANTHROPIC_BASE_URLen PowerShell, y búscala en el bloqueenvde tus archivos de configuración. Cuando está establecida, Claude Code envía las solicitudes al modelo a esa dirección en lugar de aapi.anthropic.com, por lo que un valor residual que apunta a un proxy o gateway local que ya no se está ejecutando produceConnection refusedaunquecurlalcance la API. Elimínala de tu perfil de shell o de tu configuración e inicia Claude Code desde una nueva terminal. - En Linux y WSL, revisa
/etc/resolv.confen busca de un servidor de nombres inaccesible. WSL en particular puede heredar un resolvedor defectuoso del host. - En macOS, un cliente VPN que se desconectó o desinstaló puede dejar una interfaz de túnel o una regla de enrutamiento. Revisa
ifconfigen busca de interfacesutunobsoletas y elimina la extensión de red de la VPN en Configuración del Sistema. - Docker Desktop y runtimes de contenedores similares pueden interceptar el tráfico saliente. Ciérralos y vuelve a intentarlo para descartar esta causa.
Unable to connect to Anthropic services
Durante la configuración de la primera ejecución, Claude Code verifica que puede alcanzarapi.anthropic.com y platform.claude.com antes de mostrar el paso de inicio de sesión. Cuando alguna de las verificaciones falla, Claude Code imprime el motivo y sale.
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://, podía quedarse detenida en Checking connectivity... indefinidamente y luego fallar aunque las solicitudes a la API a través del mismo proxy tuvieran éxito.
Claude Code omite esta verificación cuando un archivo de configuración administrada, una política MDM o un asistente de políticas 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 del gateway. Antes de v2.1.247, Claude Code ejecutaba la verificación también con esta configuración, y salía con este error cuando los endpoints de Anthropic eran inaccesibles.
Claude Code también omite la verificación en una máquina sin configuración administrada cuando tu propio ~/.claude/settings.json nombra un gateway con forceLoginMethod y forceLoginGatewayUrl. Antes de v2.1.295, Claude Code ejecutaba la verificación en ese caso.
Qué hacer:
- Si el mensaje nombra una variable de proxy, verifica que su valor apunte al proxy correcto y pide a tu equipo de red que permita conexiones HTTPS a través de él hacia el host del mensaje. Consulta Configuración de red.
- Revisa las comprobaciones de Unable to connect to API. La prueba con
curly las indicaciones sobre el firewall de esa sección también se aplican a esta verificación. - Si tu red está abierta y el fallo persiste, es posible que Claude Code no esté disponible en tu país
Socket is closed
Socket is closed significa que la conexión que transportaba una respuesta en streaming se cerró mientras la respuesta aún estaba llegando. La causa más común es un proxy corporativo en Windows que corta un túnel establecido a mitad de la respuesta.
Según cuánto haya avanzado la respuesta, Claude Code reintenta la solicitud, conserva lo que Claude produjo o termina el turno. Consulta 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 ves este error, actualiza a v2.1.214 o posterior con
claude updatey luego envía tu mensaje de nuevo - Si los turnos siguen fallando detrás del mismo proxy después de actualizar, revisa Unable to connect to API y verifica la configuración del proxy en Configuración de red
API returned an empty or malformed response
Claude Code muestra este error cuando su reintento sin streaming de una solicitud en streaming fallida obtiene un estado HTTP de éxito pero el cuerpo no es un mensaje de la API de Claude: comúnmente una página HTML de error o de inicio de sesión, un cuerpo vacío o JSON en otro formato. La fuente habitual es un proxy, un gateway o una página de inicio de sesión de la red que responde en lugar de la API. Claude Code no reintenta la solicitud, y el turno termina con este error.- Una cláusula
Response:con el tipo de contenido, el tipo de cuerpo, comobody is an HTML pageoempty body, su tamaño en bytes y si la respuesta incluía un id de solicitud de Anthropic. Cuando la respuesta nombra un servidor reconocible, comonginxocloudflare, o incluye encabezados de intermediarios, comocf-rayovia, la cláusula también los enumera. - Una oración que nombra el id de la solicitud en streaming fallida y el fallo que desencadenó el reintento. Cuando se había abierto un stream antes del fallo, también informa cuántos eventos del stream llegaron y, si llegó alguno, cuánto tiempo llevaba el stream en silencio cuando el intento falló.
intercepting the request.
Antes de v2.1.271, una respuesta que incluía un mensaje de API válido con un tipo de contenido que no es JSON, como text/plain, también terminaba el turno con este error. Algunos gateways LLM usan ese tipo de contenido para la respuesta sin streaming.
Qué hacer:
- Lee la cláusula
Response:para ver qué sistema respondió. Un cuerpo HTML, la ausencia de id de solicitud de Anthropic o un servidor nombrado comonginxocloudflaresignifican que algo entre Claude Code y la API respondió en su lugar - Si enrutas a través de un gateway LLM, prueba la ruta con una solicitud directa y corrige el salto que devuelve la respuesta que no es de la API
- En una red con página de inicio de sesión, como una Wi-Fi de invitados, completa el inicio de sesión en un navegador y luego vuelve a intentarlo
- Si solo está rota la ruta sin streaming a través de tu gateway, establece
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1para desactivar este respaldo, excepto cuando el propio endpoint de streaming devuelve404, caso en el que Claude Code sigue recurriendo al respaldo
Streaming response ended before any complete data was received
Una respuesta en streaming de tu proveedor de modelos se completó sin entregar ningún dato utilizable, por lo que Claude Code reenvió la solicitud sin streaming 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 sin streaming de forma silenciosa.- Configura cualquier proxy o gateway entre Claude Code y tu proveedor de modelos para que deje pasar sin modificar los cuerpos de las respuestas en streaming y sus encabezados
- En Amazon Bedrock, consulta Errores de streaming detrás de un gateway o proxy para conocer los requisitos de encabezados y cuerpo
La respuesta en streaming de Bedrock tiene un content-type inesperado
Un gateway o proxy entre Claude Code y Amazon Bedrock está transformando el cuerpo de la respuesta en streaming o su encabezadoContent-Type. Amazon Bedrock envía las respuestas en streaming como application/vnd.amazon.eventstream. En lugar de decodificar un cuerpo que no puede leer, Claude Code rechaza una respuesta en streaming exitosa que informa un content-type diferente. Claude Code no reintenta la solicitud.
API Error: Truncated event message received después de que toda la respuesta se había almacenado en búfer.
Qué hacer:
- Configura el gateway para que deje pasar sin modificar el cuerpo de la respuesta de
InvokeModelWithResponseStreamy su encabezadoContent-Type. Un intermediario que reemite el stream como eventos enviados por el servidor es una causa común. - Establecer
CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1oculta este error, pero Claude Code no decodifica un cuerpo binario con un encabezado reescrito, por lo que esas solicitudes recurren a una ruta más lenta sin streaming. Consulta Errores de streaming detrás de un gateway o proxy.
Errores de certificado SSL
Un proxy o dispositivo de seguridad de tu red está interceptando el tráfico TLS con su propio certificado, y Claude Code no confía en él.Check your proxy or corporate SSL certificates, sin el código de OpenSSL ni la sugerencia de 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 de agotar el presupuesto de reintentos completo. Las versiones anteriores pasaban unos minutos reintentando antes de mostrarlo. Las condiciones TLS transitorias, como un tiempo de espera agotado en el handshake, todavía se reintentan.
Durante /login y la verificación de conectividad al inicio, el mismo fallo produce un mensaje diferente:
- Exporta el paquete de CA de tu organización y apunta Claude Code a él con
NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem - Consulta Configuración de red para ver las instrucciones de configuración completas
- No establezcas
NODE_TLS_REJECT_UNAUTHORIZED=0, que desactiva por completo la validación de certificados
Host no permitido en una sesión en la nube
En una sesión en la nube o en una tarea programada en la nube, un403 o un error de DNS como ENOTFOUND puede significar que el host solicitado no está en la lista de permitidos del entorno en la nube. Para confirmarlo, compara el host con esa lista. Un 403 con este encabezado confirma el bloqueo, pero no todos los 403 de solicitudes bloqueadas lo incluyen:
- Tráfico de GitHub y de conectores: las operaciones de GitHub y el tráfico de los conectores MCP usan canales separados, por eso pueden seguir funcionando mientras otros hosts están bloqueados
- Entorno predeterminado: el entorno Default usa acceso Limited con Allow package managers marcado. Sus sesiones alcanzan la lista de permitidos predeterminada de registros de paquetes, API de proveedores de nube, registros de contenedores y dominios de desarrollo comunes.
- Abre tu entorno para editarlo, ya sea desde el formulario de la tarea programada en la nube o desde el selector de entornos donde inicias sesiones en la nube.
- En el diálogo Edit cloud environment, selecciona Limited en Network access y luego agrega el dominio bloqueado a Allowed domains. Ingresa un dominio por línea. Marca Allow package managers para permitir la lista de permitidos predeterminada junto con tus propios dominios. Selecciona Full en su lugar si quieres acceso sin restricciones.
- Haz 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, consulta cuándo llega un cambio de acceso a la red a las sesiones existentes.
The proxy refused the connection
Ves este mensaje cuando Claude lee un artefacto a través del proxy que estableciste enHTTPS_PROXY o en 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 hacia ese host. Cuando el proxy se niega, nada llega al host, y el mensaje incluye el estado HTTP del proxy:
CONNECT. El host nunca respondió, así que cada estado apunta a una solución diferente:
HTTP 407: el proxy requiere credenciales que no recibió. Inclúyelas en la URL del proxy, como muestra Autenticación básica.HTTP 403: el proxy se niega a abrir un túnel hacia*.frame.claudeusercontent.com. Pide a quien administra el proxy que permita ese host, que figura en Requisitos de acceso a la red.- Cualquier otro estado, como
HTTP 502: el proxy no abrió el túnel por un motivo propio, como no poder alcanzar el host. Busca el estado en los registros del proxy. unreadable replyen lugar de un estado: lo que hay en la dirección del proxy no respondió con una línea de estado HTTP. Verifica que la dirección corresponda a un proxy HTTP.
- Revisa la dirección y las credenciales en la variable de proxy, como se describe en Configuración de proxy, y luego ejecuta
curl -x http://proxy.example.com:8080 -I https://api.anthropic.comdesde el shell en el que inicias Claude Code, usando tu propia URL de proxy. En Windows PowerShell, ejecutacurl.exe. Si esta prueba falla de la misma manera, corrige primero la configuración del proxy. Si tiene éxito, el rechazo es específico del host del artefacto. - Si tu red permite que Claude Code alcance el host del artefacto directamente, agrega
.frame.claudeusercontent.comaNO_PROXY. Mantén la entrada así de acotada: una entrada más amplia como.claudeusercontent.comtambién omite el proxy parabridge.claudeusercontent.com, que las organizaciones con listas de IP permitidas necesitan mantener en el proxy.
El servicio de entornos en la nube devolvió una respuesta vacía o inesperada
Claude Code solicita tu lista de entornos en la nube en varios momentos, como cuando creas una sesión en la nube desde la CLI o ejecutas/remote-env. Cuando no puede leer la respuesta del servidor, muestra uno de estos mensajes:
couldn't list environments: en el diálogo de /remote-env.
Qué hacer:
- Vuelve a intentar la acción. Claude Code solicita la lista de nuevo cada vez
- Si el mensaje sigue apareciendo, consulta status.claude.com para ver si hay incidentes activos
Failed to fetch session from Sessions API
Este mensaje significa que Claude Code encontró la sesión en la nube que pediste traer a tu terminal, pero no pudo leer su historial de conversación desde los servidores de Anthropic, por lo que no la abrió:claude --teleport, /teleport o al elegir la sesión en la lista de /tasks. claude --teleport <session-id> lo imprime y sale con el código 1.
Qué hacer:
- Ejecuta el mismo teleport de nuevo. Si falla de la misma manera, reporta el problema
Couldn’t load the history of cloud session
Este mensaje significa que Claude Code encontró la sesión en la nube que pediste traer a tu terminal, pero la solicitud de su historial de conversación devolvió que no se encontró:- Abre el enlace del mensaje para revisar la sesión en tu navegador. Si se abre ahí y el mismo teleport vuelve a fallar de esta manera, reporta el problema.
Couldn’t reconnect to your Remote Control session
claude --resume o claude --continue, Claude Code se vuelve a conectar a la sesión de Remote Control registrada en esa conversación. Este mensaje significa que la reconexión falló por un motivo que puede ser temporal, como una interrupción de la red o un error del servidor, por lo que Claude Code no puede confirmar si la sesión remota todavía existe. Tu sesión local sigue ejecutándose sin Remote Control.
Qué hacer:
- Ejecuta
/remote-controlpara reintentar la conexión - Inicia una nueva sesión con
claude --remote-controlpara crear una nueva sesión de Remote Control - Para otros mensajes de inicio de Remote Control, consulta Solución de problemas de Remote Control
Previous session is unavailable — run /remote-control to start a new one.
Sessions ended while this machine was offline
Claude Code muestra este mensaje en la terminal que ejecutaclaude remote-control después de que tu máquina estuvo sin conexión el tiempo suficiente para que el servidor limpiara el entorno de Remote Control que tu máquina estaba atendiendo. Las sesiones de ese entorno terminaron y no puedes reanudarlas. El número indica cuántas sesiones terminaron.
- Cuando Claude Code enumere worktrees conservados debajo de este mensaje, recupera de ellos cualquier trabajo sin confirmar
- Ejecuta
claude remote-controlpara iniciar un entorno nuevo
Couldn’t share the transcript
Después de que aceptas compartir la transcripción de tu sesión desde una encuesta, como la encuesta de calidad de la sesión, Claude Code la sube a Anthropic, o en su lugar guarda un archivo local en proveedores de terceros, en sesiones del gateway de aplicaciones de Claude y cuando no hay credenciales de Anthropic disponibles. Este mensaje significa que no se completó el envío.- Ejecuta
/feedbackpara enviar la transcripción con una descripción de lo que sucedió. Consulta Reportar un error si/feedbackno está disponible en tu entorno - Si otras solicitudes también están fallando, revisa tu conexión de red y consulta Unable to connect to API
Couldn’t send feedback
Un mensaje que empieza conCouldn't send feedback significa que el servicio de comentarios no confirmó el informe que enviaste desde el diálogo de /feedback, /bug o /share, o un borrador de comentarios en cola. Considéralo como no recibido. Cuando después de los dos puntos sigue una oración sobre tu organización, tu organización rechaza los comentarios.
El segundo ejemplo es el rechazo de una organización:
- Sin sesión iniciada: el mensaje continúa con
: not signed in. Run /login, then retry.Ejecuta/loginy vuelve a enviar - Rechazo de tu organización: por ejemplo,
: Feedback has not been enabled for your organization.o: Feedback collection is not available for organizations with custom data retention policies.A partir de entonces,/feedbackpuede responder durante siete días que está desactivado por la política de tu organización. Un borrador en cola permanece en la cola y aun así caduca según lo programado - Credenciales rechazadas: el mensaje continúa con
: the sign-in this session uses is not allowed to send feedbacko: the server did not accept the credentials this session uses. Ejecuta/statusen el prompt de Claude Code para ver qué inicio de sesión, token o clave de API envía esta sesión (request timed out)o(couldn't reach the service)justo después deCouldn't send feedback: vuelve a enviar el informe o el borrador en cola. El diálogo conserva tu texto, y el mensaje de un borrador en cola diceThe draft is still queued.Si otras solicitudes también están fallando, revisa tu conexión de red y consulta Unable to connect to API. Si sigue fallando, presenta el informe en github.com/anthropics/claude-code/issues(server returned <status>), o ningún motivo, justo después deCouldn't send feedback: el estado es el código de respuesta del servicio. El mensaje propio del servicio lo sigue cuando se envió uno, como en(server returned 403: Access Forbidden). Si sigue fallando, presenta el informe en github.com/anthropics/claude-code/issues
Feedback payload too large
Este mensaje en la pantalla de revisión de un borrador de comentarios significa que Claude Code no tiene confirmación de que el servicio aceptó el borrador. Considéralo como no recibido. El borrador permanece en tu cola de/feedback, así que puedes volver a enviarlo.
- En la pantalla de revisión, establece Send transcript en
noy luego vuelve a enviar el borrador. Acortar los detalles elimina como máximo 10 KB de texto, que es todo lo que pueden contener los detalles de un borrador.
Se agotó el tiempo de espera de la conexión al servidor MCP durante una suspensión o un cambio de reloj
Este mensaje significa que se agotó el tiempo de espera de una conexión a un servidor MCP y que Claude Code detectó que el reloj de tu sistema se adelantó durante el intento:- En una sesión interactiva: ejecuta
/mcp, selecciona el servidor y selecciona Reconnect - En tu shell: vuelve a ejecutar el comando
claude -p,claude mcp listoclaude mcp get. Si el servidor falla entonces con un mensaje que empieza conSkipping connection (recent failure cached, espera 15 minutos y vuelve a ejecutar el comando. - En una aplicación del Agent SDK: llama a
reconnectMcpServer()en TypeScript o aClaudeSDKClient.reconnect_mcp_server()en Python - Si el servidor vuelve a fallar: si el mensaje es distinto de este, consulta qué revisar cuando un servidor MCP no se conecta. Si este mensaje vuelve a aparecer aunque tu computadora se mantuvo activa y nada cambió su reloj, consulta Reportar un error.
MCP server "<name>" connection timed out after <N>ms en lugar de este.
Errores de solicitud
Estos errores se relacionan con el contenido de tu solicitud. La mayoría provienen de la API después de que rechazó la solicitud; algunos los produce Claude Code localmente antes de enviar cualquier solicitud.El prompt es demasiado largo
La conversación más los archivos adjuntos superan la ventana de contexto del modelo./clear cuando DISABLE_COMPACT está configurado. Las formas más largas del error, como la forma de compactación fallida que aparece más abajo, mantienen la redacción Prompt is too long ·. En la salida de -p y en la transcripción, el texto sigue siendo Prompt is too long.
Cuando desactivaste la compactación automática en tu configuración de usuario, la línea también lo indica:
/config escribe autoCompactEnabled en la configuración de usuario. La sugerencia aparece solo cuando un cambio en /config tendría efecto. Por ejemplo, no aparece cuando DISABLE_AUTO_COMPACT o DISABLE_COMPACT desactivaron la compactación automática. Tampoco aparece cuando un alcance de mayor precedencia, como la configuración del proyecto o la configuración administrada, estableció autoCompactEnabled en false. Antes de v2.1.235, la línea no incluía ninguna sugerencia sobre la 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 con ella y /compact fallaba con el mismo error.
Un gateway de aplicaciones de Claude reporta esta condición como capability_rejected: prompt_too_long cuando un proveedor de nube upstream rechaza la solicitud con el formato de error propio 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 con él.
Cuando la compactación automática se ejecutó en este turno y falló por un error subyacente, como un modelo no disponible o un fallo de autenticación, el mensaje nombra ese error después de un separador:
/compact falla con el mismo error hasta que lo hagas. 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 ante este error, normalmente resume tus intercambios más antiguos y conserva los más recientes. Como último recurso, Claude Code resume de otra manera:
- Cuando no puede resumir ningún intercambio completo, Claude Code conserva tu prompt más reciente palabra por palabra y resume todo lo anterior.
- En ese caso, cuando la conversación no termina con tu prompt, Claude Code resume toda la conversación en su lugar.
/clear para empezar de nuevo. Antes de v2.1.269, la compactación fallaba siempre que no podía resumir un intercambio completo, por lo que una sesión en ese estado volvía a encontrar este error en cada turno.
Una conversación de un solo intercambio no tiene turnos anteriores que resumir. Cuando la compactación automática se habría ejecutado en una, Claude Code omite el intento y explica en su lugar qué llena la solicitud. Cuando la API no reporta conteos de tokens en su error, el mensaje dice:
Prompt is too long cuando fallaba.
Qué hacer:
- Ejecuta
/compactpara resumir los turnos anteriores y liberar espacio, o/clearpara empezar de nuevo. Si/compactrespondeNot enough messages to compact., la conversación es un solo intercambio sin nada anterior que resumir, así que el espacio lo ocupan ese único prompt y lo que Claude Code envía con cada solicitud: ejecuta/cleary vuelve a enviarlo con menos texto pegado o adjuntos más pequeños, o reduce las definiciones de herramientas y los archivos de memoria siguiendo los pasos a continuación - Ejecuta
/contextpara ver un desglose de lo que está consumiendo la ventana: prompt del sistema, herramientas, archivos de memoria y mensajes - Desactiva los servidores MCP que no estés usando con
/mcp disable <name>para quitar sus definiciones de herramientas del contexto - Recorta los archivos de memoria
CLAUDE.mdgrandes, o mueve las instrucciones a reglas limitadas a rutas que se carguen solo cuando sean relevantes - La compactación automática está activada de forma predeterminada y normalmente evita este error. Si la desactivaste en
/configo conDISABLE_AUTO_COMPACT, vuelve a activarla. Si la mantienes desactivada, ejecuta/compacttú mismo antes de que se llene la ventana. - Si Claude Code advirtió que no reconoce el ID de tu modelo, la advertencia puede nombrar la ventana que asumió. Cuando la ventana real del modelo es distinta, indícale a Claude Code la ventana real.
- Si usas un
ANTHROPIC_BASE_URLpersonalizado y el error empieza conPrompt is too long · automatic compaction failed, establece la ventana de contexto del modelo o actualiza a v2.1.299 o posterior. Antes de v2.1.299, Claude Code terminaba el turno con ese mensaje cerca de la ventana asumida de 200K en lugar de enviar la solicitud.
- Si usas un
- Si el error apareció justo después de que detuviste a Claude mientras compactaba la conversación, tu conversación no cambió y sigue siendo lo bastante grande como para necesitar compactación. Ejecuta
/compacty vuelve a enviar tu mensaje. Para evitar que el error se repita, actualiza Claude Code a v2.1.304 o posterior. Antes de v2.1.304, detenerlo en ese momento podía terminar el turno con este error. - En v2.1.305, con muchas herramientas MCP y una conexión directa a la API de Anthropic, este error puede ocultar un error 400 o 422 no relacionado de la API. Actualiza Claude Code a v2.1.306 o posterior para ver el error original.
El contexto supera el límite de tokens
/context muestra esta advertencia al principio de su salida cuando la conversación ha crecido más allá de la ventana de contexto del modelo:
Context exceeds, no necesitas ejecutar ninguno de los dos comandos mientras la compactación automática esté activada, que es lo predeterminado:
- Compactación automática activada: envía tu siguiente mensaje. Si aún falla con
Prompt is too long, consulta esa entrada. - Compactación automática desactivada: en la sesión, ejecuta
/compactsi la advertencia lo menciona, o/clearpara empezar de nuevo. Hasta que ejecutes uno, los mensajes fallan conContext limit reached, o conPrompt is too longen la salida de-p.
/clear en lugar de /compact cuando estableciste DISABLE_COMPACT.
Qué hacer:
- Después de una advertencia de ventana de compactación: en una conversación de varios turnos, ejecuta
/compactpara resumir los turnos anteriores y liberar espacio. Para empezar de nuevo, ejecuta/clear. - Para conocer más formas de reducir el uso, consulta El prompt es demasiado largo
/context mostraba un uso superior al 100% sin ninguna línea de advertencia que explicara qué significaba eso o cómo recuperarse.
Solicitud demasiado grande
El cuerpo sin procesar de la solicitud superó el límite de 32MB de la API antes de la tokenización, generalmente por contenido pegado de gran tamaño, resultados de herramientas o adjuntos. Este límite es independiente de la ventana de contexto.Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).: las imágenes o documentos hicieron que la solicitud superara el límite. Claude Code reintenta sin ellos.Request too large for the API's 32MB request limit: los mensajes por sí solos superan el límite, así que el mensaje dicecompacting cannot make it fity Claude Code no reintenta. En modo no interactivo, el mensaje te indica que reduzcas la entrada o que inicies una nueva sesión.
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 sobre adjuntos en cada rechazo, incluso cuando compactar no podía ayudar.
Qué hacer:
- Si el mensaje dice
compacting cannot make it fit, presiona Esc dos veces para retroceder antes del turno que agregó el contenido grande, o ejecuta/clearpara empezar de nuevo - De lo contrario, ejecuta
/compact, que elimina las imágenes y los adjuntos acumulados - Haz referencia a los archivos grandes por su ruta en lugar de pegar su contenido, para que Claude pueda leerlos por fragmentos
- Para imágenes, consulta La imagen era demasiado grande a continuación
La imagen era demasiado grande
Una imagen pegada o adjunta supera los límites de tamaño o de dimensiones de la API.could not be processed and was removed significa que la API rechazó una imagen de la conversación, por ejemplo una que supera los límites de tamaño o dimensiones.
Si alguno de estos errores sigue apareciendo, actualiza Claude Code. En versiones anteriores, un error de imagen podía repetirse por motivos como estos:
- Antes de v2.1.299, en una conversación larga con muchas imágenes, Claude Code podía quitar las últimas imágenes que adjuntaste en lugar de la que superaba el límite. La línea
was removedse repetía entonces en cada turno, y Claude no veía tus imágenes nuevas. - Antes de v2.1.299, en VS Code, la app de Desktop y el Agent SDK, las imágenes que adjuntabas mientras Claude estaba trabajando no recibían el redimensionamiento que reciben otras imágenes adjuntas. Llegaban a la API en su tamaño original, lo que provocaba errores de imagen repetidos en conversaciones largas.
- Antes de v2.1.166, una imagen pegada podía permanecer en la conversación, y el mismo error se repetía entonces en cada mensaje posterior
- Cambia el tamaño de la imagen antes de pegarla. La API acepta imágenes de hasta 8000 píxeles en el lado más largo para una sola imagen, o 3000 píxeles cuando hay más de 20 imágenes en el contexto.
- Toma una captura de pantalla más ajustada de la región relevante en lugar de la pantalla completa
- Para el mensaje
dimension limit for many-image requests, ejecuta/compacten el prompt de Claude Code si el mensaje lo menciona, o inicia una nueva sesión con menos imágenes
dimension limit for many-image requests muestra el límite de píxeles indicado en el error de la API.
No se pudo cambiar el tamaño de la imagen
Claude Code no pudo reducir una imagen adjunta antes de enviarla a la API.2576x2576px donde estos ejemplos dicen 2000x2000px.
Qué hacer:
- Si el mensaje te pide que conviertas la imagen, conviértela a PNG, JPEG, GIF o WebP y vuelve a adjuntarla. Claude Code puede verificar las dimensiones de estos formatos a partir del encabezado del archivo, sin decodificar la imagen.
- Si el mensaje reporta un límite de dimensiones o de tamaño, redimensiona o vuelve a comprimir 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, vuelve a guardar la imagen en el formato que sugiere el mensaje y adjúntala de nuevo.
Request rejected as unprocessable by the model
La API rechazó la solicitud como una que el modelo no puede procesar. El mensaje es el propio de la API.- Si el mensaje sigue apareciendo en una conversación con imágenes o documentos, quítalos tú mismo. Presiona Esc dos veces para retroceder antes de los turnos que los agregaron, o ejecuta
/clearpara empezar de cero.
Errores de PDF
El PDF que adjuntaste no se pudo procesar. Los mensajes se muestran aquí en su forma no interactiva; en una sesión interactiva, en cambio, te piden que presiones esc dos veces y lo intentes de nuevo.- Para PDF demasiado grandes, pídele a Claude que lea un rango de páginas con la herramienta Read en lugar de adjuntar el archivo completo, o extrae el texto con una herramienta como
pdftotexty haz referencia al archivo de salida por su ruta - Para PDF protegidos o no válidos, quita la contraseña o vuelve a exportar el archivo desde su aplicación de origen, y luego inténtalo de nuevo
pdftoppm. Instala poppler-utils con el comando que indica el mensaje o, en otras plataformas, una compilación de poppler que ponga pdftoppm en tu PATH. Consulta Comportamiento de la herramienta Read para saber qué PDF se leen por rango de páginas.
No se permiten entradas adicionales
El endpoint que recibió la solicitud rechazó uno de los campos de la solicitud como una entrada que no acepta, y el mensaje del endpoint nombra ese campo.context_management y defer_loading de la búsqueda de herramientas, 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. Cuando un gateway reenvía un cuerpo en formato de Anthropic a un upstream con un esquema diferente, ese upstream rechaza esos campos. Pares de encabezado beta y campo del cuerpo cubre ambos casos.
Qué hacer:
- Si el mensaje contiene
context_management: Extra inputs are not permitted, actualiza Claude Code a v2.1.304 o posterior. Después de actualizar, Claude Code responde a este rechazo enviando la solicitud una vez más sin el campo. Antes de v2.1.304, Claude Code no reintentaba ante este rechazo. - Si el mensaje nombra
defer_loadingotool_reference, actualiza Claude Code a la v2.1.305 o posterior. Claude Code responde entonces a este rechazo enviando la solicitud una vez más sin los campos de búsqueda de herramientas. - Si tu gateway descarta el encabezado, configúralo para que reenvíe el encabezado
anthropic-beta. Consulta transferencia de funciones para saber qué deben reenviar los gateways. - Como alternativa, establece
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1antes de iniciar. Desactivar las capacidades de versión preliminar describe el alcance exacto.
diagnostics sin que hubiera ningún gateway de por medio. Aparecía cuando una sesión que ya había usado la Anthropic API pasaba a Amazon Bedrock o al Agent Platform de Google Cloud sin reiniciarse. Por ejemplo, una sesión que dejaste abierta pasa a Bedrock cuando ejecutas /setup-bedrock en otra ventana de Claude Code. En esas versiones, ejecuta /clear en esa sesión o reiníciala.
El esquema de entrada de la herramienta no es válido
Una herramienta de la solicitud declaró uninput_schema que no supera la validación de JSON Schema 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 puedas buscar.
$schema un dialecto de JSON Schema distinto de draft 2020-12. Claude Code no valida esos esquemas contra el metaesquema de JSON Schema, aunque la verificación de los nombres de propiedad de nivel superior sigue aplicándose.
Antes de v2.1.216, ningún despliegue ejecutaba las verificaciones de exclusión.
Qué hacer:
- Si tu versión de Claude Code es anterior a v2.1.300, ejecuta
claude updateen tu shell. Antes de v2.1.300, Claude Code no reintentaba la solicitud sin los parámetros de la herramienta rechazada, así que este error se repetía en cada solicitud que incluía la herramienta. - Elimina o desactiva el servidor MCP que declara el esquema no válido. El error identifica la herramienta solo por su posición. En v2.1.216 o posterior, revisa el registro de cada servidor en busca de una línea que nombre una herramienta cuyo esquema de entrada sería rechazado. Si ningún registro nombra una, desactiva los servidores de uno en uno.
- Si mantienes el servidor, corrige el
input_schemade la herramienta. El esquema debe ser JSON Schema válido, y los nombres de propiedad de nivel superior deben tener entre 1 y 64 caracteres y usar solo letras y dígitos ASCII,_,.y-. Consulta Herramientas con esquemas de entrada no válidos.
Nombre de herramienta MCP de más de 128 caracteres
Un servidor MCP enumera una herramienta cuyo nombre completo, comomcp__<server>__<tool>, supera los 128 caracteres que acepta la API. Claude Code deja esa herramienta fuera de las herramientas que envía a Claude, y las demás herramientas del servidor siguen funcionando. En una sesión que inicias con claude --debug desde tu shell, Claude Code escribe este mensaje en el registro de depuración en ~/.claude/debug/<session-id>.txt:
- Si mantienes el servidor, acorta el nombre de la herramienta.
- Si el servidor está en tu configuración de MCP, dale ahí un nombre más corto, como
dben lugar deanalytics-database. Luego actualiza lo que hace referencia al servidor o a sus herramientas con el nombre anterior, como las reglas de permisos y los matchers de hooks. - Si un plugin incluye el servidor, el nombre completo de la herramienta también incluye el nombre del plugin. Pídele al mantenedor del plugin que acorte el nombre del servidor o de la herramienta.
API Error: 400 ... tools.N.custom.name: String should have at most 128 characters.
tool_use.name de más de 200 caracteres
Una llamada a herramienta en el historial de la conversación lleva un nombre más largo que los 200 caracteres que la API acepta en una solicitud:No such tool available y la conversación continúa sin este error de API.
Qué hacer:
- Ejecuta
claude updatey luego reanuda la conversación. La versión actualizada repara el nombre demasiado largo cuando carga la transcripción, así que una conversación que estaba atascada vuelve a funcionar.
/compact y --resume, por lo que este error se repetía y la conversación quedaba atascada.
Hay un problema con el modelo seleccionado
El nombre del modelo configurado no se reconoció o tu cuenta no tiene acceso a él. A partir de v2.1.160, la sugerencia final, que aquí se muestra en su forma interactiva, varía según la superficie.- CLI interactiva: ejecuta
/modelpara elegir entre los modelos disponibles para tu cuenta. - Modo no interactivo (
-p): pasa--modelcon un alias o ID válido, o estableceANTHROPIC_MODEL. En esta superficie, el texto del error muestraRun --model. - Agent SDK: el texto del error omite la sugerencia porque el modelo se establece mediante programación. Establece
modelenOptionsen TypeScript oClaudeAgentOptions(model=...)en Python, y maneja el error estructuradomodel_not_foundpara mostrar tu propio reintento o selector de modelo. - Usa un alias como
sonnetuopusen lugar de un ID completo con versión. Los alias se resuelven a un valor predeterminado que se mantiene actualizado, así que no quedan obsoletos. Consulta Configuración del modelo. - Si el modelo incorrecto sigue reapareciendo en la CLI, hay un ID obsoleto configurado en algún lugar. Revisa los lugares donde puedes establecer un modelo en orden de prioridad y elimina el valor obsoleto.
- Antes de v2.1.206, un inicio de sesión de claude.ai caducado que ya no se podía renovar hacía fallar todos los modelos con este error. Ejecuta
/loginen esas versiones. - Si
ANTHROPIC_BASE_URLapunta a un gateway de LLM y todos los modelos fallan de esta manera, comprueba que tu gateway y su upstream acepten los campos de búsqueda de herramientas. De forma predeterminada, Claude Code envía campos de herramientadefer_loadingy bloquestool_reference, con el encabezadoanthropic-betaque los habilita. Antes de la v2.1.304, la búsqueda de herramientas estaba desactivada detrás de un gateway a menos que la activaras conENABLE_TOOL_SEARCH. - Para despliegues en Agent Platform de Google Cloud, consulta Solución de problemas de Agent Platform de Google Cloud.
El modelo no es un ID de modelo reconocido
La cadena que pasaste a un cambio de modelo no es una que Claude Code pueda usar como modelo, por lo que rechazó el cambio sin enviar ninguna solicitud y la sesión mantiene su modelo actual. Puedes obtener este error cuando un modelo se establece mediante el métodosetModel() del Agent SDK, mediante una aplicación que ejecuta la CLI de Claude Code por ti, como la aplicación de escritorio, o cuando eliges un modelo desde un dispositivo conectado mediante Remote Control. Antes de v2.1.200, Claude Code guardaba la cadena y fallaba en la siguiente solicitud con Hay un problema con el modelo seleccionado.
Sonnet 5, que el mensaje repite sin el espacio. La sugerencia final nombra el alias o ID de modelo más parecido. Cuando nada se parece lo suficiente, dice Run /model to see available models. en su lugar. En una sesión que la aplicación de escritorio inicia por ti, la sugerencia sin coincidencias dice Switch to a different model.
Cuando cambias de modelo mediante el Agent SDK o una aplicación en la API de Anthropic, solo recibe este error una cadena que no puede ser un ID de modelo, como un nombre visible o una cadena vacía.
Cuando eliges un modelo desde un dispositivo con 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 configuraste, o un ID que empiece por claude- recibe este error, incluido un ID mal escrito como claud-sonnet-5. Antes de v2.1.260, esta verificación no cubría las selecciones hechas con Remote Control, por lo que una cadena no reconocida se aplicaba y fallaba en la siguiente solicitud.
Qué hacer:
- Ejecuta
/modelsin argumentos para abrir el selector y elegir entre los modelos disponibles para tu cuenta; luego pasa el alias o ID que se muestra ahí - Si usaste un alias que solo admite una versión más reciente de Claude Code, ejecuta
claude updateo, en su lugar, pasa el ID completo del modelo. El servidor aún puede exigir una versión mínima de Claude Code para ese modelo; consulta Claude Code no admite este modelo. - Esta verificación no repara un modelo guardado antes de v2.1.200. Si un valor obsoleto sigue reapareciendo, elimínalo de las ubicaciones indicadas en Establecer tu modelo.
- En cualquier proveedor distinto de la API de Anthropic, o detrás de un gateway o un
ANTHROPIC_BASE_URLpersonalizado, solo una cadena vacía recibe 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 cualquier proveedor.
Modelo no encontrado
Cambiaste a un modelo por su nombre y Claude Code no pudo confirmar que exista un modelo con ese nombre. Cuando el nombre no es un alias de modelo ni otra grafía que Claude Code acepte localmente, Claude Code lo verifica con una solicitud mínima a la API, y este error suele ser la respuesta de tu endpoint de API. Con/model <name>, un nombre que no puede ser un ID de modelo en absoluto, como uno que contiene espacios, recibe el mismo mensaje.
Try '...' instead que nombra el ID de tu proveedor para un modelo de respaldo.
Qué hacer:
- Ejecuta
/modelsin argumentos y elige entre los modelos disponibles para tu cuenta, o usa un alias de modelo comosonnet, que se resuelve a un valor predeterminado que se mantiene actualizado - Si escribiste un ID completo, compáralo con el catálogo de modelos de tu proveedor. Un modelo recién lanzado puede estar disponible en la API de Anthropic antes de que tu proveedor o región lo ofrezca.
- En el Agent SDK,
setModel()falla con este mensaje y la sesión sigue ejecutándose con su modelo anterior. En el SDK de TypeScript, llama asupportedModels()para enumerar los modelos a los que puedes cambiar. - Antes de v2.1.265,
/modeltambién rechazaba la grafía del aliasopusplan[1m]con este error. En esas versiones, actualiza Claude Code, o establece el modelo en la configuración o con--model.
No se pudo confirmar el modelo con la API
Cambiaste de modelo mediante el métodosetModel() del Agent SDK o a través de una app que ejecuta la CLI de Claude Code por ti, como la app de escritorio, y la solicitud que confirma el ID del modelo con tu endpoint de API no obtuvo respuesta en 15 segundos. La sesión conserva su modelo actual.
Try again.
Qué hacer:
- Vuelve a cambiar al modelo
- Si el cambio sigue fallando, comprueba que Claude Code pueda conectarse a tu endpoint de API; consulta Errores de red y de conexión
Error de API al verificar el modelo elegido
Elegiste 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 un motivo que no tiene una entrada propia, como un rate limit o un error del servidor. La sesión mantiene su modelo actual, y el mensaje termina indicándolo:
- Actúa según la explicación del servidor; ante un rate limit o un estado 5xx, espera y vuelve a elegir el modelo
- Los rechazos con redacción propia se tratan en las entradas cercanas, como Modelo no encontrado y El modelo está restringido por la configuración de tu organización
Claude Opus no está disponible con el plan Claude Pro
Tu plan de suscripción activo no incluye el modelo que seleccionaste.sign out and sign in again en lugar de nombrar los comandos.
Qué hacer:
- Ejecuta
/modely selecciona un modelo que incluya tu plan - Si actualizaste tu plan recientemente y aún ves esto, ejecuta
/logouty luego/login. El token almacenado refleja tu plan en el momento en que iniciaste sesión, por lo que una mejora de plan en claude.ai no tiene efecto en una sesión existente hasta que vuelvas a autenticarte. - Consulta 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 tu versión de Claude Code está por debajo de un mínimo requerido. O bien el modelo que seleccionaste requiere una versión más reciente, algo que el servidor verifica por modelo, o bien la política de tu organización la exige. El 400 incluye el código de errorclaude_code_version_too_old, y el mensaje indica qué mínimo se aplica.
- Si ejecutas
claude updateen el canal de versiones estable, no te lleva más allá de la versión estable más reciente, que aún puede estar por debajo del mínimo requerido. Cambia al canal latest y vuelve a actualizar. Si tu organización fija tu canal o tu versión mediante la configuración administrada, pídele a tu administrador que lo cambie - Con la redacción por modelo, puedes seguir trabajando en la sesión actual cambiando a otro modelo: ejecuta
/modelen la CLI, llama asetModel()en el objetoQuerydel SDK de TypeScript en modo de entrada en streaming, o llama aset_model()en elClaudeSDKClientdel SDK de Python - Con la redacción de la política de la organización, actualiza antes de continuar
El modelo está restringido por la configuración de tu organización
El administrador de tu organización deshabilitó este modelo en la consola de administración de claude.ai, o la configuración administrada lo excluye mediante una lista de permitidosavailableModels o una lista deniedModels. El aviso aparece al inicio cuando --model, ANTHROPIC_MODEL o el ajuste model indicaron 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 que la sesión pueda usar, consulta La configuración administrada bloquea el modelo predeterminado. El aviso de sustitución también puede aparecer a mitad de la sesión cuando un administrador deshabilita en la consola de administración de claude.ai el modelo con el que se está ejecutando la sesión.
/model <name> con 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 excluye la configuración administrada, dice Model '<name>' is not available. Your organization restricts model selection.
Un aviso precedido por el nombre de un agente, skill o comando significa que la restricción se aplicó al modelo solicitado por ese subagente: el subagente se ejecuta con el modelo sustituto y el modelo de tu sesión no cambia. Antes de v2.1.223, Claude Code mostraba el aviso solo para los subagentes iniciados con la herramienta Agent.
Claude Code trata un alias de familia de modelos, ya sea opus, sonnet, haiku o fable, como una solicitud de esa familia y no de su versión más reciente. En la API de Anthropic y en Claude Platform on AWS, un alias de familia restringido se resuelve a la versión más reciente de la familia que permite la configuración de tu organización, y el aviso de sustitución nombra esa versión. Claude Code rechaza /model <alias> solo cuando todas las versiones de la familia están restringidas. Antes de v2.1.205, un alias de familia se sustituía o rechazaba basándose únicamente en su versión más reciente, incluso cuando una versión anterior de la misma familia estaba permitida.
Qué hacer:
- Ejecuta
/modelpara elegir entre los modelos que permite tu organización. Los modelos restringidos no aparecen en el selector. - Si el modelo restringido se estableció en
--model, enANTHROPIC_MODEL, en el campomodelde un archivo de configuración o en el frontmattermodelde un subagente, skill o comando, elimina o actualiza ese valor para que el aviso no se repita - Si necesitas acceso al modelo restringido, pídele al administrador de tu organización que lo habilite. Consulta Restricciones de modelos de la organización.
No se puede cambiar al modelo predeterminado
Elegiste el modelo Predeterminado, por ejemplo seleccionando la fila Predeterminado en el selector de/model o escribiendo /model default. Claude Code rechazó el cambio, por lo que la sesión mantiene su modelo actual.
your organization's managed settings block it ... in "deniedModels": una lista de denegación administrada bloquea el modelo al que se resuelve la opción Predeterminadoyour organization allows only the models listed in "availableModels": una lista de permitidosavailableModelsadministrada, conavailableModelsMatchestablecido en"exact", deja fuera el modelo al que se resuelve la opción PredeterminadoClaude Code couldn't read your organization's managed settings to check which models they allow: no se pudo leer la configuración administrada, y Claude Code rechaza el cambio en lugar de aplicarlo sin verificar
- Con las redacciones de
deniedModelsyavailableModels, ejecuta/modely elige por su nombre un modelo que permita tu organización - Pídele a tu administrador que actualice el ajuste administrado que nombra el mensaje
- Con la redacción
couldn't read, reinicia Claude Code; si sigue ocurriendo, pídele a tu administrador que revise la configuración administrada
Claude Code can't start con esta configuración administrada, consulta La configuración administrada bloquea el modelo predeterminado.
Un hook PreModelSwitch bloqueó el cambio de modelo
Un hook PreModelSwitch no aprobó el cambio de modelo que tú o un cliente solicitaron, por lo que la sesión mantiene su modelo actual. Cuando el cambio provino de un host del Agent SDK o de Remote Control en lugar de un comando que escribiste, el mensaje diceModel switch blocked by a PreModelSwitch hook sin nombrar el modelo de destino.
- Un motivo escrito por un hook: un hook PreModelSwitch proporcionó ese motivo cuando denegó el cambio o pidió confirmación. Atiende lo que pide, o elige un modelo que tus hooks permitan.
PreModelSwitch hook <name> did not respond before its timeout: un hook que no responde antes de que se agote su tiempo de espera bloquea el cambio. Corrige el comando que se queda colgado o aumenta eltimeoutde ese hook, y luego vuelve a cambiar.confirmation required, and this session cannot ask: un hook respondióasksin un motivo, y una solicitud de control no tiene forma de mostrar la solicitud de confirmación. Un comando/modelen una ejecución con-preporta la misma condición con(run /model interactively to confirm)después del motivo. Haz el cambio desde una sesión interactiva, o cambia la decisión del hook para este modelo.so organization-managed PreModelSwitch hooks could not be checked: Claude Code anterior a la v2.1.323 rechaza el cambio cuando no puede determinar qué hooks PreModelSwitch proporcionan tus plugins administrados. El texto antes de esta frase indica qué falló. Para detener el rechazo, actualiza Claude Code. Para que además se ejecuten los hooks de un plugin que falló, corrige el plugin o consulta a tu administrador. Para más detalles, iniciaclaude --debugen tu shell y cambia de modelo; luego lee el registro de depuración.a PreModelSwitch hook failed before answeringoPreModelSwitch hooks were cancelled (the control stream closed) before answering: la ejecución del hook terminó sin un veredicto, y Claude Code no lo trata como una aprobación. Ejecutaclaude --debugpara ver qué falló y luego vuelve a cambiar.
plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log. Claude Code reintentaba la carga del plugin una vez y luego rechazaba los cambios posteriores en la sesión, incluso cuando tu organización no administraba ningún plugin. En esas versiones, reinicia la sesión para volver a ejecutar la carga del plugin.
No se pudo guardar como tu valor predeterminado
Elegiste un modelo para guardarlo como tu valor predeterminado, por ejemplo con/model <name> o con Enter en el selector de /model, y Claude Code no pudo escribir la selección en tu archivo de configuración de usuario, ~/.claude/settings.json. El cambio en sí se aplicó, por lo que la sesión actual se ejecuta con el modelo que elegiste, pero tu valor predeterminado no cambia y la siguiente sesión comienza con el valor anterior.
can't be written (<code>): la escritura falló con el código de error del sistema operativo que aparece entre paréntesis, comoEROFScuando el archivo, o el archivo al que enlaza, está en un sistema de archivos que rechaza escrituras. Haz que el archivo sea escribible y vuelve a cambiar. Si otra herramienta genera el archivo, establece la clavemodelen esa herramienta; consulta Un cambio que hiciste en Claude Code se pierde en las sesiones nuevas.isn't valid JSON: el archivo en disco no se puede analizar, y Claude Code lo deja intacto en lugar de sobrescribir contenido que no puede volver a leer. Corrige el error de sintaxis y vuelve a cambiar; consulta Corregir un archivo de configuración dañado.
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 podría guardarse; comprueba con qué modelo comienza tu siguiente sesión, o vuelve a ejecutar /model <name>.
Antes de v2.1.265, el aviso decía que el modelo se había saved as your default for new sessions incluso cuando la escritura fallaba.
El asesor es menos capaz que el modelo principal actual
Tu modelo asesor tiene un rango inferior al del modelo principal de tu sesión, por lo que Claude Code conserva la selección pero no adjunta el asesor a las solicitudes del modelo principal.- En una sesión interactiva, una notificación dice
Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor. - Cuando inicias con el flag
--advisoren modo no interactivo, y la ejecución no es una sesión en segundo plano, se escribe una advertencia en stderr y la ejecución se inicia de todos modos. Dice"<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.Una sesión interactiva escribe esa advertencia solo en el log de depuración.
- Elige un asesor de rango superior o un modelo principal de rango inferior. Elegir un modelo asesor muestra la clasificación y enumera los asesores aceptados para cada modelo principal.
- Deja configurado el asesor si quieres que los subagentes cuyo modelo puede asesorar sigan usándolo
thinking.type.enabled no es compatible con este modelo
Tu versión de Claude Code es anterior a la mínima requerida para el modelo seleccionado. La CLI envió una configuración de pensamiento que el modelo ya no acepta.- Ejecuta
claude updatey reinicia 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 - En el canal de versiones estable, actualizar no te lleva más allá de la versión estable más reciente, que aún puede ser anterior a estas versiones. Cambia al canal latest y luego actualiza
- Si no puedes actualizar, ejecuta
/modely selecciona Opus 4.6 o Sonnet 4.6 en su lugar - Si te encuentras con esto en el Agent SDK, actualiza el paquete del 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
Desactivaste el pensamiento extendido y ejecutaste con un nivel de esfuerzo superior ahigh. El modelo no acepta esa combinación, por lo que la API rechazó la solicitud.
· 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 ejecuta la aplicación de escritorio de Claude dice you can lower effort to High.
Qué hacer:
- Baja el nivel de esfuerzo a
higho inferior. - Vuelve a activar el pensamiento, por ejemplo quitando la definición de
MAX_THINKING_TOKENSo eliminando"alwaysThinkingEnabled": falsede tu configuración.
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 con el nivel de esfuerzo que habías establecido, por lo que Opus 5 rechazaba cada solicitud por encima de high con el pensamiento desactivado. Ahora Claude Code envía el esfuerzo high en su lugar a los modelos que sabe que rechazan la combinación, como Opus 5.
El presupuesto de pensamiento supera el límite de salida
El presupuesto de pensamiento extendido configurado supera la longitud máxima de la respuesta, por lo que no queda espacio para la respuesta en sí.- Aumenta
CLAUDE_CODE_MAX_OUTPUT_TOKENSpor encima del presupuesto de pensamiento - Consulta Pensamiento extendido para ver cómo interactúa el presupuesto con la longitud de la salida
Response exceeded the output token maximum
La respuesta de Claude alcanzó el mayor número de tokens de salida que permitía la solicitud y se cortó ahí:a request sent without streaming significa que una solicitud en streaming falló y Claude Code la volvió a enviar sin streaming, lo que limita la respuesta a 64,000 tokens de salida. Antes de v2.1.299, una respuesta cortada en una solicitud reenviada de ese modo terminaba el turno sin este mensaje, como si la respuesta estuviera completa.
Qué hacer:
- Si Claude escribió algo de texto antes de que se cortara la respuesta, responde
continueen una sesión interactiva para pedir el resto. Ese texto permanece en la conversación. - Si el mensaje indica que configures
CLAUDE_CODE_MAX_OUTPUT_TOKENS, consultaCLAUDE_CODE_MAX_OUTPUT_TOKENSpara saber cómo se limita el valor y Configurar variables de entorno para saber dónde configurarla - Para mantener cada respuesta por debajo del límite, pídele a Claude la salida en partes más pequeñas, como un archivo o una sección por respuesta
Desajuste en bloques de uso de herramientas o de pensamiento
El historial de la conversación llegó a la API en un estado inconsistente.tool_use, tool_result y thinking del historial ya no coincide con lo que espera la API.
Qué hacer:
- Si estás usando Opus 4.7 u Opus 4.8, ejecuta primero
claude update. Las versiones anteriores a v2.1.156 pueden provocar este error durante el uso normal de herramientas, y/rewindno lo resuelve. - Ejecuta
/rewind, o presiona Esc dos veces, para retroceder a un checkpoint anterior al turno dañado y continuar desde ahí. Consulta Checkpointing para ver cómo se crean y restauran los checkpoints.
Datos no válidos en el bloque redacted_thinking
La API rechazó la solicitud con un 400 porque no pudo aceptar un bloqueredacted_thinking que lleva un turno anterior del historial de la conversación.
- Si estás en v2.1.281 o anterior y cada turno falla con este error, ejecuta
claude updatey reanuda la sesión - Si el error persiste, ejecuta
/clearpara iniciar 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 muestra una vista previa de una sesión guardada, elimina el contenido de herramientas que la API de Anthropic no acepta y deja esta línea donde el contenido eliminado estaba entre dos bloques de pensamiento:ANTHROPIC_BASE_URL que traduce las llamadas a 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 cual cuando la sesión se ejecuta a través de un proxy o en otro proveedor. Antes de v2.1.246, Claude Code volvía a enviar a la API el uso de la herramienta y su resultado, 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:
- No necesitas hacer nada cuando ves la línea de marcador de posición. La sesión continúa sin el contenido eliminado.
- Si, en cambio, cada turno de una sesión reanudada falla con el error 400, ejecuta
claude updatey vuelve a reanudar la sesión. 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 hay un mensaje del sistema en una posición de la conversación que no acepta:use the top-level 'system' parameter for the initial system prompt, reciben la misma recuperación.
Cuando el error sí aparece, el mensaje del sistema rechazado no es uno que Claude Code pueda eliminar. Eso suele significar que un proxy o gateway de 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 gateway configurado mediante
ANTHROPIC_BASE_URL, conéctate sin el proxy para confirmar el origen e informa el error a quien lo opere - Ejecuta
/clearpara iniciar una conversación nueva. Si el error también vuelve a aparecer ahí, la causa está en la ruta de la solicitud, no en la conversación guardada.
encrypted_content no válido en el bloque search_result
La API rechazó la solicitud con un 400 porque el historial de la conversación contiene contenido de búsqueda web alojada que no puede descifrar. La redacción nombra el campo que no puede leer:encrypted_stdout se refiere a la salida de un programa de ejecución de código alojado que leyó esos resultados, que la API también cifra. La API rechaza una solicitud que vuelve a enviar contenido que no puede descifrar, como contenido generado para otra organización.
La propia herramienta WebSearch de Claude Code registra los resultados de búsqueda como texto sin formato, por lo que estos bloques suelen llegar a una conversación a través de un proxy o gateway de LLM que ejecutó por sí mismo la búsqueda web alojada.
Con las tres redacciones de búsqueda web, Claude Code deja fuera de lo que envía las llamadas de búsqueda, los resultados y las citas, y reintenta la solicitud una vez, por lo que la sesión continúa sin mostrar el error. La redacción de encrypted_stdout no tiene esa recuperación, así que ese mensaje todavía te llega. Antes de v2.1.282, Claude Code también conservaba los bloques de búsqueda web rechazados, y cada turno posterior y /compact fallaban de la misma manera.
Qué hacer:
- Si estás en v2.1.281 o anterior y cada turno falla con una de las redacciones de búsqueda web, ejecuta
claude updatey reanuda la sesión - Si el error persiste, o el mensaje nombra
encrypted_stdout, ejecuta/rewindpara retroceder a un checkpoint anterior al turno que agregó el contenido, o ejecuta/clearpara iniciar una conversación que no lo lleve - Si ejecutas Claude Code detrás de un proxy o gateway, informa el error a quien lo opere
Rechazo por la Política de uso
La API se negó a responder porque el contenido de la conversación activó una verificación de la Política de uso. Si el mensaje incluye la líneaDetails: `[reasoning_extraction]`, consulta Las protecciones marcaron una solicitud del razonamiento de Claude.
El mensaje incluye un ID de solicitud y un ID de mensaje que puedes citarle al soporte si crees que el rechazo es incorrecto.
Claude cuando no hay ningún modelo registrado.
La verificación evalúa la conversación completa, no solo tu prompt más reciente, por lo que enviar un mensaje nuevo en la misma sesión suele volver a provocar el mismo rechazo. Lo mismo ocurre si sales y vuelves a abrir la sesión con --continue o --resume, ya que la transcripción en disco sigue conteniendo el contenido que lo provocó. En Amazon Bedrock, Agent Platform de Google Cloud y Microsoft Foundry, este mensaje también cubre las solicitudes que las medidas de seguridad del modelo marcaron como un tema de ciberseguridad. Consulta Las medidas de seguridad marcaron un tema de ciberseguridad.
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:
- Presiona Esc dos veces o ejecuta
/rewindpara retroceder a un checkpoint anterior al turno que provocó el rechazo, y luego reformula o adopta un enfoque diferente. Consulta Checkpointing. - Si no puedes identificar qué turno lo provocó, ejecuta
/clearpara iniciar una conversación nueva en el mismo proyecto. Tu conversación anterior se conserva en disco y sigue disponible en/resume. - En modo no interactivo (
-p), donde no es posible retroceder, reintenta con un prompt reformulado en una nueva sesión sin--continue. Las verificaciones de la política varían según el modelo, así que en algunos casos cambiar a otro modelo con--modeltambién puede resolver el rechazo.
Las medidas de seguridad marcaron un tema de ciberseguridad
Las medidas de seguridad del modelo marcaron contenido de la conversación como un tema de ciberseguridad. El mensaje nombra el modelo que marcó la solicitud:Details: `[reasoning_extraction]`, consulta Las protecciones marcaron una solicitud del razonamiento de Claude.
Este mensaje enlaza al Cyber Verification Program, que otorga acceso para trabajo legítimo de ciberseguridad. Los modelos con respaldo automático de modelo muestran un mensaje diferente, sin este enlace; en Opus 5.5 y Sonnet 5.5 comienza con <model>'s safeguards flagged this session. Esa sección también explica cuándo Claude Code cambia de modelo en su lugar.
En Amazon Bedrock, Agent Platform de Google Cloud y Microsoft Foundry, una marca de ciberseguridad produce en su lugar el mensaje de rechazo por la Política de uso.
Qué hacer:
- Si tu trabajo requiere este contenido, solicita acceso a través del Cyber Verification Program
- Si tu solicitud no trataba sobre un tema de ciberseguridad, ejecuta
/feedbackpara reportar el falso positivo - Para seguir trabajando en la misma sesión, presiona Esc dos veces o ejecuta
/rewindpara retroceder a un checkpoint anterior al turno que activó la marca, y luego adopta un enfoque diferente. Consulta Checkpointing.
- De v2.1.219 a v2.1.296, el mensaje también podía incluir
Apply to the Cyber Verification Program to reduce these interruptions.antes de su oración final - 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 al centro de ayuda. En sesiones interactivas, continuaba conIf 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 a un formulario de exención
Las protecciones marcaron una solicitud del razonamiento de Claude
La API rechazó la solicitud porque las protecciones la marcaron por pedirle al modelo que reprodujera su razonamiento interno en la respuesta. La API denomina esta categoría de rechazoreasoning_extraction, y el mensaje de rechazo incluye esta línea:
Details.
Qué hacer:
- Elimina o reformula cualquier instrucción que le pida a Claude que escriba su pensamiento o razonamiento de forma literal o en un formato fijo, como una sección
<thinking>, una sección de borrador o un camporeasoningen una salida JSON. La instrucción puede estar en tu prompt o en una personalización que Claude Code carga junto con él, como CLAUDE.md, un skill, el prompt de un subagente, un estilo de salida o la descripción de una herramienta MCP. - Para comprobar si una personalización es la causa, ejecuta
claude --safe-modeen tu terminal para iniciar una sesión con las personalizaciones desactivadas y luego envía el mismo prompt - Después de cambiar una personalización, inicia una nueva sesión
- Para reformular un prompt que ya enviaste, consulta Retroceder y resumir
- Aún puedes pedirle a Claude que explique su respuesta. Pide una explicación breve, la evidencia detrás de un resultado o un resumen de las acciones que realizó. Para leer resúmenes del pensamiento de Claude, consulta
showThinkingSummaries. - Para ver más ejemplos, y qué hacer si una solicitud reformulada sigue siendo rechazada, consulta Mantener el razonamiento en los bloques de pensamiento
Output blocked by content filtering policy
El filtro de contenido de salida de la API detuvo la respuesta que Claude estaba generando. El texto del mensaje proviene de la API:- Reformula tu último mensaje o adopta un enfoque diferente
- Para retroceder a un checkpoint anterior al turno que provocó el bloqueo, presiona Esc dos veces o ejecuta
/rewind. Consulta Checkpointing
Errores de la línea de comandos
Estos errores provienen de la línea de comandosclaude 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 un trabajo en segundo plano al que nunca era posible conectarse.
- Quita
-po--print.--bgrecibe el prompt como su argumento posicional, así queclaude --bg "<task>"es el comando completo. Consulta Despachar nuevos agentes desde tu shell. - Para ejecutar el prompt de forma no interactiva e imprimir el resultado en lugar de crear una sesión en segundo plano, quita
--bgy ejecutaclaude -p "<task>"
Couldn’t tell whether --bg is a flag or text
Ejecutaste claude con --bg o --background en una posición donde Claude Code no pudo determinar si lo usabas como el flag de segundo plano o como texto. El comando no inició nada, imprimió esta línea y salió con el código 1:
--background, la línea menciona --background en su lugar.
Qué hacer:
- Para iniciar una sesión en segundo plano, vuelve a ejecutar el comando en tu shell con el flag primero:
claude --bg --name nightly-audit "<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:
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, integra 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 comprueba y la sesión se inicia; un valor leído desde un archivo se comprueba en cada inicio. Antes de v2.1.242, Claude Code iniciaba la sesión de todos modos.
- Cuando el valor empieza con
{pero no se puede analizar como JSON, o el contenido de un archivo de--agentsno se puede analizar, Claude Code imprime una líneainvalid JSON:con el mensaje propio del analizador JSON - Cuando se puede analizar pero una definición de agente no coincide con el esquema de los subagentes definidos por CLI, Claude Code imprime una línea por cada problema
- Cuando el nombre de un agente empieza con
-, Claude Code imprime<name>: agent names must not start with '-'
…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 solo aceptaba 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 estos:
Error: --agents takes a JSON object, or a file path only with --print (-p): Claude Code interpretó el valor como una ruta de archivo en una sesión interactiva. Pasa las definiciones como JSON en línea, o agrega-ppara leerlas desde un archivo.Error: --agents file not found: <path>: no existe ningún archivo en esa ruta. Un valor que no empieza con{y no es JSON válido se lee como una ruta, así que el JSON en línea que tu shell alteró también puede fallar de esta manera. Revisa la ruta o las comillas y vuelve a ejecutar el comando.
- Corrige cada problema que enumera el mensaje y luego 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:
- Ejecuta la tarea localmente en la sesión restringida
- Si controlas cómo se inició la sesión, inicia una nueva sesión de
claudesin--restrictedy crea la sesión en la nube desde allí
--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íticaallow_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:
/teleport, /remote-env o /web-setup. Antes de v2.1.268, enviar uno de esos comandos devolvía Unknown command en su lugar.
Si el mensaje, en cambio, nombra una credencial que usa esta sesión y termina con Cloud sessions use your claude.ai login., consulta Cloud sessions use your claude.ai login. Si Claude Code no pudo cargar la política de tu organización en absoluto, verás un mensaje diferente.
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
Cloud sessions use your claude.ai login
Cuando el rechazo por política nombra una credencial que usa esta sesión y termina con esta oración, Claude Code verificó la política de sesiones en la nube de la organización que emitió esa credencial. Esa organización puede ser distinta de aquella a la que pertenece tu inicio de sesión de claude.ai:--cloud o --teleport. Antes de v2.1.296, Claude Code también imprimía en este caso la forma que te indica contactar al administrador de tu organización.
Couldn’t verify your organization’s policy for cloud sessions
Estos mensajes significan que Claude Code no pudo cargar la política de tu organización, que verifica antes de crear, reanudar o enviar un mensaje a una sesión en la nube. Mientras la solicitud de la política no ha terminado, el mensaje es:/teleport o /web-setup, también muestra este mensaje. Lo hace incluso cuando tu shell imprimiría una forma Cloud sessions aren't available:, y su segunda oración dice Check your network connection, then restart Claude Code and try again.
Una vez que la solicitud de la política ha fallado, el mensaje indica qué falló. Esto aplica cuando inicias, reanudas o envías un mensaje a una sesión en la nube desde tu shell con un flag como --cloud o --teleport. Sin ruta hacia la API, dice:
ANTHROPIC_API_KEY, el mensaje también puede nombrarla e indicar que la elimines:
Couldn't verify.
Qué hacer:
- Para el mensaje
Couldn't verify, revisa tu conexión de red e inténtalo de nuevo. Dentro de una sesión, reinicia Claude Code primero - Para un mensaje
Cloud sessions aren't available:, haz lo que requiera su causa, como revisar tu proxy o eliminar la credencial que nombra, y luego vuelve a ejecutar el comando
No se guardó nada en el stash porque una carpeta reemplazó un archivo con seguimiento
Este mensaje significa que ahora hay una carpeta en tu checkout donde antes había un archivo o enlace con seguimiento en git. Aparece después de que eliges la opción de stash al traer una sesión en la nube a tu terminal, por ejemplo conclaude --teleport o /teleport. Guardar ese estado en el stash podría eliminar los archivos dentro de la carpeta, así que Claude Code rechaza el stash y deja tu checkout y tu índice sin cambios:
- Haz commit del cambio o mueve la carpeta a otro lugar, como indica el mensaje, y luego vuelve a ejecutar el teleport
El valor de --json-schema no es un JSON Schema válido
El esquema que pasaste a --json-schema en modo no interactivo no superó 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.
format, como "format": "email", son válidos: Claude Code acepta format como anotación y no lo aplica.
Claude Code ejecuta dos comprobaciones antes de la compilación del esquema: rechaza un valor que no es JSON analizable con Error: --json-schema is not valid JSON, y un JSON válido que no es 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 Obtener salida estructurada 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 pesa más de 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.
--settings que no sea un archivo regular: 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
--settingsa un archivo de configuración JSON regular de menos de 2 MiB. Consulta Configuración para ver el formato.
Configuration error in ~/.claude.json
Claude Code no pudo analizar~/.claude.json, el archivo que contiene los datos de tu cuenta, los servidores MCP y el estado de cada proyecto. Un inicio no interactivo como claude -p termina con el código 1.
Cuando Claude Code encuentra una copia de seguridad, la salida la menciona e imprime una línea cp que la copia de vuelta:
- La salida tiene una línea
cp: ejecuta esa línea en tu terminal. En Windows, ejecútala en PowerShell. - La salida no tiene una línea
cp, o el error vuelve después de ejecutarla: si~/.claude.jsontodavía tiene tu configuración, corrige su JSON. Si no puedes, copia encima otro archivo.claude.json.backup.<timestamp>de~/.claude/backups/si existe, o cámbiale el nombre. Sin ningún archivo en~/.claude.json, Claude Code se inicia con la configuración predeterminada y sin nada de lo que contenía el archivo. ~/.claude.jsonya no tiene tu configuración: busca un archivo.claude.json.corrupted.<timestamp>que todavía la tenga, en~/.claude/backups/o en tu directorio home. Corrige su JSON y luego cópialo sobre~/.claude.json. Si no puedes encontrar ni corregir ninguno, intenta los mismos pasos con un archivo.claude.json.backup.<timestamp>que tenga tu configuración. Si ninguno la tiene, cambia el nombre de~/.claude.jsony vuelve a agregar tus servidores MCP conclaude mcp add.
Claude configuration file was empty and no backup holds anything
Este mensaje al iniciar significa que el archivo que menciona estaba en blanco y ninguna de las copias.backup del archivo contiene nada. Claude Code se inició con los valores predeterminados para lo que contiene ese archivo. Tus archivos settings.json y .mcp.json son archivos separados.
- Vuelve a configurar lo que tenías en ese archivo. Por ejemplo, agrega tus servidores MCP de alcance
userylocalconclaude mcp adddesde tu terminal. - Vuelve a iniciar sesión si Claude Code te lo pide
El directorio actual ya no existe
Iniciasteclaude 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 un stack ENOENT ... uv_cwd sin procesar en stderr en lugar de este mensaje.
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 aplicación de terminal a esa carpeta. Otros comandos que leen esa carpeta fallan de la misma manera: 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 sigue apuntando al que se eliminó. Ejecuta
cd "$PWD"o sal del directorio y vuelve a entrar, y luego vuelve a ejecutarclaude - Para
EPERMen macOS, cierra tu aplicación de terminal con Cmd+Q, ábrela de nuevo, vuelve a esa carpeta y ejecutaclaude. Silsen esa carpeta sigue fallando, abre System Settings > Privacy & Security > Files and Folders, activa la carpeta para tu aplicación de terminal y luego vuelve a abrir la terminal
Directorio temporal rechazado o imposible de 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:
- Para
could not be createdseguido deis full (ENOSPC), libera espacio en disco en el volumen que nombra el mensaje. Cuando diceyour disk quota on the volume holding /tmp is used up (EDQUOT)en su lugar, elimina los archivos propios de ese volumen que ya no necesites - Para las formas
Refusing to use it, elimina la propia entrada nombrada, no aquello a lo que apunta un enlace, y vuelve a iniciar Claude Code; para la formaowned by uid, solo un administrador o ese usuario puede eliminarla - Para
is not readable, ejecutachmod 0700sobre el directorio nombrado, o elimínalo y vuelve a iniciar - En cualquiera de estos casos, establece
CLAUDE_CODE_TMPDIRen un directorio que controles y vuelve a iniciar Claude Code, sin tocar la ruta rechazada
ENOSPC: no space left on device, mkdir '/tmp/claude-501', y se aplican los mismos pasos.
Claude Code no pudo guardar porque el disco está lleno
Esta línea en stderr después de una ejecución declaude -p significa que el disco está lleno o tu cuota de disco se agotó, así que Claude Code no pudo guardar todo lo de la ejecución:
json, la ejecución termina con código 1, y la respuesta ya se imprimió. Con salida stream-json, la ejecución conserva su código de salida habitual, y la respuesta llega de todos modos.
Qué hacer:
the disk is full (ENOSPC): antes de tu próxima ejecución, libera espacio en el disco que contiene la ruta del mensajeyour disk quota is used up (EDQUOT): antes de tu próxima ejecución, libera espacio o solicita una cuota mayor
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:
- 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 el contenido de
.claude/del directorio no se cargó
/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
Si
claude ultrareview imprimió Error: Workspace not trusted, consulta Workspace not trusted al ejecutar claude ultrareview en su lugar.claude remote-control o su alias claude rc en un directorio en el que no has confiado, y el comando no pudo preguntarte si querías 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. 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í.
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
claudeahí 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í
Workspace not trusted al ejecutar claude ultrareview
En una carpeta en la que no has confiado, cuandoclaude ultrareview no puede preguntar si confías en ella, la ejecución termina con el código 1 antes de que comience la revisión:
claude ultrareview --json > findings.json, significa que la salida estándar no es una terminal.
Qué hacer:
- En un script o un trabajo de CI, agrega
--trust-workspaceal final para confiar en la carpeta durante esa ejecución:claude ultrareview --trust-workspace. Agrégalo solo para código en el que confíes, porque git y Claude Code pueden entonces ejecutar programas nombrados en la configuración de git y en la configuración del proyecto de la carpeta. Para un pull request cuyo código no te inspira confianza, ejecuta la revisión desde una rama en la que confíes. - En tu propia máquina, ejecuta
claudeen esa carpeta y acepta el diálogo de confianza del espacio de trabajo, y luego vuelve a ejecutar tu comando original
/ultrareview y /code-review ultra pueden detenerse con Ultrareview did not start: "<folder>" is not trusted, and this session started without asking whether you trust it. Inicia claude en esa carpeta sin IS_DEMO establecida, acepta el diálogo de confianza del espacio de trabajo y ejecuta el comando en la nueva sesión.
Cada uno de estos mensajes de claude ultrareview significa que no se inició ninguna revisión y que el código de salida es 1:
Error: Workspace not trusted. This terminal ...: la terminal no informó su número de filas y columnas, o no cabe la pregunta de confianza con sus advertencias. Agrándala o usa una terminal que informe su tamaño, y luego vuelve a ejecutarclaude ultrareview. Fuera de tu directorio home, también puedes ejecutarclaudeen esa carpeta una vez y aceptar el diálogo de confianza, para que las ejecuciones posteriores ahí no pregunten.Error: Workspace not trusted. <folder> is your home directory: como la confianza para tu directorio home nunca se guarda, ejecutarclaudeahí primero no sirve. Ejecutaclaude ultrareviewdesde un directorio de proyecto en su lugar, después de ejecutarclaudeahí una vez para aceptar el diálogo de confianza, o agrega--trust-workspaceal final.No answer in time.seguido deError: Workspace not trusted: la preguntaTrust <folder>? [y/N]quedó sin respuesta durante 5 minutos. Vuelve a ejecutarclaude ultrareviewy respóndela.Ultrareview did not start: <folder> is not trusted: rechazaste la preguntaTrust <folder>? [y/N], por ejemplo respondiendono presionando Enter. Para iniciar la revisión, vuelve a ejecutarclaude ultrareviewy respondey.Ultrareview did not start: `--trust-workspace` takes no value: algo que no es un flag sigue a--trust-workspace, como un número de PR ofalse. Si no confías en la carpeta, omite el flag. Para confiar en ella durante esta ejecución, coloca el número de PR o la rama base antes del flag:claude ultrareview 1234 --trust-workspace.
claude ultrareview no aceptaba --trust-workspace.
Remote Control no se inició porque una pregunta no obtuvo respuesta
Este mensaje significa queclaude remote-control hizo la pregunta de primera ejecución citada en el mensaje y no obtuvo respuesta:
Enable Remote Control?: en un script o un servicio, la entrada estándar termina antes de que alguien pueda responder. Ejecutaclaude remote-controluna vez en una terminal, como el usuario con el que se ejecuta tu script o servicio, y respondey.Choose [1/2] (default: 1):: vuelve a ejecutarclaude remote-controly elige un modo de creación, o pasa--spawn=same-diro--spawn=worktreepara omitir la pregunta
No se transfiere a las sesiones que inicia Remote Control
Iniciaste Remote Control con un flag global declaude 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:
--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 con un flag global que aún 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 --helplas enumera - Cuando el flag rechazado sea
--permission-mode, ejecutaclaude remote-control --permission-mode <mode>para establecer el modo de permisos de las sesiones que inicia Remote Control
claude remote-control no aceptaba sus propios flags cuando un flag global iba primero, y el comando fallaba con un error unknown option.
Remote Control no se inició por el archivo de --settings
El archivo que pasaste a claude remote-control --settings tiene un problema:
- Corrige el problema que indica el mensaje y luego vuelve a ejecutar tu comando
claude remote-control
The settings file has changed since Remote Control started
Este mensaje en la terminal que ejecutaclaude remote-control significa que las sesiones no se iniciarán a partir del archivo que pasaste a --settings tal como está ahora:
- Para usar el archivo tal como está ahora, detén
claude remote-controly vuelve a ejecutar el mismo comando. Para recuperar las sesiones que estaba atendiendo, consulta Reanudar sesiones después de detener el servidor. - Para conservar la configuración con la que se inició Remote Control, restaura el contenido del archivo tal como estaba y luego vuelve a ejecutar el comando si
claude remote-controlha terminado
--sandbox or --no-sandbox is not supported by claude remote-control
Este error significa que el comando que inicia tu servidor de Remote Control pasa --sandbox o --no-sandbox después de remote-control, y claude remote-control no acepta ninguno de los dos flags. El servidor termina con el código 1 en lugar de iniciarse:
- Quita el flag del comando, incluso en un script o una definición de servicio que inicie el servidor por ti, y luego vuelve a ejecutarlo
- Para ejecutar en el sandbox las sesiones que inicia el servidor, activa el sandboxing definiendo
sandbox.enabledcomotrueen un archivo de configuración
claude remote-control en v2.1.300, así que un comando escrito para una versión anterior todavía puede incluir uno.
claude import todavía no está disponible en esta compilación
Ejecutasteclaude 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 mediante un feature flag que obtiene de Anthropic y almacena en caché en el 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 importpuede imprimir esto aunque 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 aplicaciones de Claude. Claude Code no obtiene feature flags en estas sesiones, así que
claude importsigue sin estar disponible. - Estableciste
DISABLE_TELEMETRY,DO_NOT_TRACK,CLAUDE_CODE_DISABLE_FEATURE_FLAGS,DISABLE_GROWTHBOOKoCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, que desactivan la obtención de feature flags, así queclaude importsigue sin estar disponible.
- En una instalación nueva, inicia
claude, espera a que se cargue la sesión, sal y vuelve a ejecutarclaude import - Donde la obtención de feature flags siga desactivada, prepara la configuración tú mismo: agrega servidores MCP con
claude mcp add, y crea los archivosCLAUDE.md, los skills y comandos y los subagentes que quieras transferir. El mensaje también nombra~/.claude/settings.json. De la configuración que transfiereclaude import, ese archivo solo contiene el modo de permisos; Claude Code no lee servidores MCP desde él.
No se pudo leer la configuración de Claude Code
Ejecutasteclaude import mientras Claude Code no podía analizar ~/.claude.json, el archivo donde almacena los datos de tu cuenta y el estado por proyecto. El subcomando lee ese archivo para verificar la disponibilidad, pero no muestra el diálogo de recuperación que muestra la sesión interactiva, así que sale con el 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.
- Ejecuta
claudesin argumentos. Claude Code detecta el archivo no válido y ofrece restablecerlo. Luego vuelve a ejecutarclaude import. - Para conservar las ediciones manuales que hayas hecho, corrige en su lugar la sintaxis JSON de
~/.claude.jsonen un editor y luego vuelve a ejecutarclaude import
No se pudo importar un servidor desde Claude Desktop
Claude Code no pudo agregar uno de los servidores que seleccionaste enclaude 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.
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.jsonpara que use solo letras, números, guiones y guiones bajos, y vuelve a ejecutarclaude mcp add-from-claude-desktop - Agrega ese servidor directamente con
claude mcp addoclaude mcp add-jsoncon un nombre válido. Consulta Importar servidores MCP desde Claude Desktop.
No se puede agregar el servidor MCP al alcance managed
Ejecutasteclaude 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.
- Agrega el servidor a un alcance en el que puedas escribir:
local,useroproject. Sin--scope, el comando usalocal. Consulta Alcances de instalación de MCP - Para proporcionar el servidor a todos los usuarios de tu organización, agrégalo a
managedMcpServersen la configuración administrada que despliegas
No se puede agregar el servidor MCP cuando la configuración administrada solo permite servidores de plugins
Ejecutasteclaude 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:
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 y aun así 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
managedMcpServerssi es un servidor remoto HTTP o SSE
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 regular o pesa más de 2 MiB, así que termina con este error en lugar de leer el archivo.
.mcp.json dejaba el comando esperando indefinidamente sin ninguna salida, y un enlace simbólico a un archivo de dispositivo como /dev/zero hacía crecer la memoria hasta que se terminaba el proceso.
Qué hacer:
- Comprueba qué hay en
.mcp.jsonen tu directorio actual. Reemplázalo por un archivo JSON normal en el formato de alcance de proyecto, o elimínalo, y luego vuelve a ejecutar el comando.
El servidor MCP no se guardó ni se eliminó
Este error significa que un comando comoclaude mcp add o claude mcp remove no logró llevar tu cambio a ~/.claude.json. Es posible que otros procesos de Claude Code hayan mantenido el archivo bloqueado, o que el archivo sea de solo lectura o esté protegido por un sandbox.
was not removed from en lugar de was not saved to, y remove the server again en lugar de add the server again. Para un servidor de alcance local, la ruta va seguida del directorio de proyecto al que pertenece la entrada, como (local scope for /path/to/project).
Qué hacer:
- Hay otros procesos de Claude Code en ejecución: el comando espera entre 10 y 20 segundos aproximadamente por el bloqueo del archivo y luego se rinde sin escribir. Vuelve a ejecutar el mismo comando con
CLAUDE_CODE_CONFIG_LOCK_WAIT_MSestablecido en una espera más larga en milisegundos, como60000. - El archivo es de solo lectura o está protegido por un sandbox: haz que el archivo que menciona el mensaje tenga permisos de escritura y vuelve a ejecutar el mismo comando de agregar o eliminar, o ejecuta ese comando fuera del sandbox.
claude mcp add, claude mcp add-json y claude mcp remove informaban éxito incluso cuando el cambio no llegaba al archivo. Antes de v2.1.318, el mensaje no mencionaba el bloqueo, y Claude Code no leía CLAUDE_CODE_CONFIG_LOCK_WAIT_MS.
Es posible que el servidor MCP no se haya guardado o eliminado
Ejecutasteclaude 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 en el disco. Los paréntesis después de to confirm the change indican el motivo.
may not have been removed y termina con then remove the server again if it is still listed. Si el motivo es the file was not found, es posible que el servidor siga configurado.
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 el disco. Para un servidor de alcancelocal, 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 autentica mediante un proveedor de identidad de terceros. Estos hosts incluyenmicrosoft365.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.
- 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 cuyoheadersHelper 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:
- Ejecuta tú mismo el comando
headersHelperde 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.jsonde proyecto, un plugin o un archivo de agente de proyecto. Comprueba que imprima un valor deAuthorizationque el endpoint del servidor acepte - Después de corregir el helper o el origen de su credencial, selecciona el servidor en
/mcpy elige Reconnect
Authorization. Ese descubrimiento podía fallar con Incompatible auth server: does not support dynamic client registration en lugar de informar la credencial rechazada.
El servidor MCP rechazó la capacidad de elicitación
Un servidor MCP construido con Java MCP SDK 0.11.0 a 0.17.0 rechazó la conexión. Esas versiones del SDK no pueden analizar los modos de elicitaciónform y url que Claude Code declara en su handshake. El mensaje dice:
- Actualiza el servidor a Java MCP SDK 0.17.1 o posterior, o a una de las versiones de Spring AI que menciona el mensaje
- O agrega
"bareElicitationCapability": truea la entrada de ese servidor en tu configuración de MCP y luego reinicia Claude Code. El campo se acepta en entradas stdio,sse,httpywsy requiere Claude Code v2.1.281 o posterior
.mcp.json establece el campo para un servidor HTTP:
/mcp muestra el servidor como conectado. Claude Code declara el modo form solo a ese servidor, así que elimina el campo una vez que lo actualices.
Un servidor también puede fallar con su propio texto de error, como uno que contenga Unrecognized field "form". Se aplican las mismas soluciones.
No se encontró la herramienta de solicitud de permisos de MCP
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 hasta el tiempo de espera de conexión por servidor de 30 segundos establecido por MCP_TIMEOUT a que ese servidor se conecte. Antes de v2.1.206, el inicio no esperaba a que el servidor terminara de conectarse, así que un servidor sano pero lento en iniciar también producía este error.
Available MCP tools: nombra las herramientas MCP que estaban conectadas.
Qué hacer:
- Comprueba que el servidor se inicie y permanezca conectado: ejecuta
claude mcp listen el mismo directorio y confirma que el servidor aparece como conectado - Confirma que el nombre de la herramienta coincide con el nombre
mcp__<server>__<tool>que expone el servidor - Si el servidor necesita más de 30 segundos para iniciarse, 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 del inicio de sesión. Si otro proceso ocupa el puerto que necesita ese listener, el inicio de sesión falla con este mensaje. Esto ocurre sobre todo con un puerto de callback fijo establecido mediante la variableMCP_OAUTH_CALLBACK_PORT o --callback-port, ya que sin uno Claude Code elige un puerto disponible.
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_PORTo--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 del 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 en127.0.0.1, por ejemplo un software de seguridad o una política de sandbox que deniega los listeners locales.
- Comprueba si un 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 su contexto de revisión generando el diff de tu rama contra origin/HEAD, la ref local que registra qué rama es la predeterminada en tu remoto origin. Cuando esa ref no existe, los comandos de git que recopilan el diff fallan y la revisión se detiene antes de empezar.
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 cual ocurre con un git clone completo de un remoto con commits. La ref 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
Shell command permission check failed for pattern "...": la comprobación de permisos del comando no lo permitió. Consulta Comprobaciones de permisos en comandos inyectados para ver qué resultados abortan en cada modo de permisos y cuándoallowed-toolsaprueba previamente un comandoSkill <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 ashell: powershell. Consulta Cómo se ejecutan los comandos inyectados
- Crea la ref nombrando la rama predeterminada de tu remoto:
git remote set-head origin <default-branch>. Esto funciona siempre que exista la ref de seguimiento localorigin/<default-branch>. Si no existe, como en los clones de una sola rama, primero obtén la rama: ejecutagit remote set-branches --add origin <branch>, luegogit fetch origin, y después vuelve a ejecutar el comando set-head. Vuelve a ejecutar/security-review. - Si prefieres no nombrar la rama, ejecuta
git fetch originy luegogit remote set-head origin --auto, que pregunta al remoto cuál es su rama predeterminada. Falla conerror: Cannot determine remote HEADcuando 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 conerror: Not a valid refcuando 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 ref. Si el remoto está vacío, primero sube tu rama congit push -u origin HEADy nombra esa rama en el comando set-head;origin/HEADapunta entonces a la rama que acabas de subir, así que/security-reviewve un diff vacío hasta que la rama diverja de ella.
No shell command in a skill or command was run
No shell command in <name> was run significa que un comando de contexto dinámico !`<command>` en ese archivo de skill o comando contiene un carácter que la herramienta Bash o PowerShell rechaza:
- Cualquiera de las dos herramientas: un carácter de control sin procesar distinto de una tabulación o un salto de línea
- Herramienta PowerShell: también U+FEFF o U+180E
�, como en este ejemplo de la herramienta Bash:
- Busca cada
�en el comando citado al final del mensaje. Elimina el carácter que representa del archivo de skill o comando, o de los argumentos u opciones que se sustituyen en el archivo.
Skill, comando o hook por encima del límite de 4,000,000 caracteres
Un mensaje conmore than 4,000,000 characters significa que un skill, un comando o un hook de prompt o de agente no se ejecutó. Si pegaste texto largo como argumentos, guárdalo en un archivo, ejecuta /clear, ya que el texto permanece en la conversación, y luego pasa su ruta. Fuera de Code Mode, un hook de prompt o de agente PreToolUse que supera el límite no bloquea la llamada. Usa un hook de comando, que no tiene ese límite.
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. Ese 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.
- Para uso interactivo, ejecuta
claudeen 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 uso puntual, pasa el prompt:
claude -p "your question", o canalízalo conecho "your question" | claude -p
Claude Code no puede leer el teclado aquí
Ejecutasteclaude sin -p, lo que inicia una sesión interactiva, pero su entrada estándar no es una terminal. Algo la canalizó o la redirigió, o el programa que inició claude proporcionó su propio flujo de entrada.
Una sesión interactiva necesita una terminal desde la cual leer tus pulsaciones de teclas, y lo que hace Claude Code sin una depende de tu plataforma:
- Windows: Claude Code imprime el mensaje en stderr y termina con código 1 en lugar de iniciar la interfaz
- macOS y Linux: Claude Code lee tus pulsaciones de teclas desde
/dev/ttye inicia la sesión, con cualquier texto canalizado como tu primer prompt. Ves el mensaje cuando no se puede abrir/dev/tty, y su primera línea nombra/dev/ttyen lugar del texto de Windows.
- Para trabajar de forma interactiva, ejecuta
claudedirectamente en una terminal, sin canalizar ni redirigir su entrada - Para obtener una respuesta sin la interfaz interactiva, por ejemplo desde un script, agrega
-py proporciona el prompt como argumento o por stdin, como enclaude -p "your question"oecho "your question" | claude -p. Lo mismo funciona con--continuey--resume <session-id>.
Raw mode is not supported.
Si ves Raw mode is not supported durante claude install, consulta Raw mode is not supported durante la instalación.
La entrada solo contenía espacios en blanco
En modo no interactivo, Claude Code rechaza un prompt compuesto solo 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:claudetermina conError: 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-jsono 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 del resultado del turno:Blank prompt — the message was only whitespace, so nothing was sent to the model.
- 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 declaude -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 búfer. El mensaje expresa ese límite como 256M. Antes de v2.1.257, Claude Code almacenaba esa entrada en búfer sin límite, haciendo crecer la memoria hasta que el proceso fallaba o se terminaba.
- Comprueba 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 -plee de forma predeterminada un prompt de texto plano desde stdin
Comando desconocido
En una sesión interactiva de terminal, 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 algo:
- Un error tipográfico, como
/heplpor/help. Cómo el menú de comandos coincide con lo que escribes 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. Consulta la entrada de
/web-setup,/scheduleo/auto-mode-setup. Algunos comandos responden con su propio mensaje cuando la política de tu organización los desactiva, comoCloud 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
/ sin coincidencia solo en una sesión interactiva de terminal. En cualquier otra sesión, 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 aplicación de escritorio
- El panel de chat de la extensión de VS Code
- Sesiones en la nube y tareas programadas en la nube
Unknown command.
Claude Code no trata como comando todo prompt que empiece con /. Envía el prompt a Claude como un mensaje normal cuando la primera palabra después de / empieza 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 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 solo mostraba las estadísticas sin procesar del diff.
PR #<N> is too large for ultrareview y nombra la cantidad 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 mover esos 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 necesita 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 rastreados en lugar de rechazarla. Ves este rechazo cuando la rama base no se encuentra en absoluto, cuando Claude Code no puede verificar que tu clon esté completo, o en el raro repositorio donde el diff de todo el árbol no es posible, como con el formato de objetos SHA-256.
- No pasaste una rama base: Claude Code comparó contra la rama predeterminada del repositorio y sugiere pasar tu 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 (shallow), sugieregit fetch --unshallow originen su lugar. Antes de la v2.1.221, la sugerencia proponíagit fetch --unshallow originpara toda rama base obtenida, y en un clon completo ese comando falla confatal: --unshallow on a complete repository does not make sense.
- Si otra rama es tu base real, pásala explícitamente:
/code-review ultra <branch> - Si es posible que tu clon no tenga el historial completo, ejecuta
git fetch --unshallow originy vuelve a ejecutar la revisión
Tu checkout no tiene ramas
Un checkout puede tener commits pero ninguna rama: si ejecutasgit init seguido de git fetch <url> y git checkout FETCH_HEAD, obtienes un HEAD desvinculado sin refs. Claude Code empaqueta tu repositorio como un bundle de git para subirlo a un ultrareview, y no puede empaquetar un repositorio que no tiene ramas ni otras refs, 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.
- Crea una rama en tu commit actual con
git checkout -b <name>y luego 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.
/web-setup no está disponible en tu sesión, el mensaje solo nombra el enlace de claude.ai.
Qué hacer:
- Ejecuta
/web-setuppara conectar el inicio de sesión de tu GitHub CLI 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
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.
/web-setup no está disponible en tu sesión, el mensaje solo nombra la instalación de la aplicación.
Qué hacer:
- Si tu CLI
ghlocal puede leer el repositorio, ejecuta/web-setuppara conectar ese inicio de sesión a tu cuenta de Claude - Vuelve a ejecutar la revisión después del cambio
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 construir 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 empieza con lo que detuvo el bundle, por ejemploCould not upload repo bundle (<error>), y termina con la oración de la comprobación previa:
- 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 inicio del mensaje nombra lo que detuvo la subida. Cuando esa causa es algo que puedes corregir, corrígelo para que la sesión pueda iniciarse desde tu repositorio local
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 el disco. En su lugar, Claude Code rechaza la subida y no se sube nada: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:
/schedule, el mismo mensaje aparece como una nota de configuración que menciona el repositorio; la nota no impide crear la tarea.
Qué hacer:
- Ejecuta
/web-setuppara conectar el inicio de sesión de tu GitHub CLI a tu cuenta de Claude, o conecta una cuenta en claude.ai/connect-github. Consulta Opciones de autenticación de GitHub para ver en qué se diferencian ambas. - Vuelve a ejecutar el comando un minuto después de conectarte
Una política de la organización de GitHub está bloqueando a Claude
Ejecutaste un comando en el prompt de Claude Code que inicia una sesión en la nube, como/autofix-pr. Antes de crear la sesión, Claude Code verifica el acceso de Claude al repositorio en GitHub, y GitHub lo rechazó porque tu organización de GitHub tiene una política que bloquea a Claude. Claude Code se detiene ahí y muestra un mensaje que nombra la política.
Cuando lo que bloquea el acceso es una lista de IP permitidas, el mensaje dice:
- Lista de IP permitidas: pide a un propietario de tu organización o empresa de GitHub que permita las direcciones IP de salida de Anthropic. Consulta Listas de permitidos y firewalls de GitHub para conocer las direcciones y la configuración de GitHub que debes cambiar.
- Inicio de sesión único: desconecta GitHub en claude.ai/customize/connectors y luego vuelve a conectarlo. Cuando GitHub lo solicite, haz clic en Authorize junto a tu organización para que la nueva conexión quede autorizada para su inicio de sesión único.
- Política de acceso condicional: pide a tu administrador de GitHub Enterprise o de Microsoft Entra ID que permita a Claude en esa política
- Después del cambio, vuelve a ejecutar el comando
Se necesita autorización de inicio de sesión único
Ejecutaste/install-github-app y elegiste un repositorio cuya organización exige inicio de sesión único SAML. Antes de la configuración, Claude Code verifica tu acceso al repositorio con la CLI de GitHub, y GitHub rechazó esa verificación porque tu token de gh todavía no está autorizado para la organización. El asistente muestra la advertencia con los pasos para autorizarlo:
- Vuelve a autorizar tu inicio de sesión en la CLI de GitHub con los alcances
repoyworkflowejecutandogh auth refresh -h github.com -s repo,workflow, y autoriza la organización cuando GitHub te 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
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 declaude --resume, así que termina el proceso en lugar de continuar en un estado parcialmente cargado. El mensaje incluye el comando para reintentar:
/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 manera, ejecuta
claude updatey 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
claudepara iniciar una nueva sesión
No se encontró ninguna conversación con el ID de sesión
Pasaste un ID de sesión aclaude --resume <session-id> y ninguna transcripción guardada coincidió con él:
- ID mal escrito: en una ejecución no interactiva, el ID es el campo
session_idde la salida de--output-format json - Transcripción eliminada: Claude Code elimina las transcripciones después del período de retención, de 30 días por defecto, según 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 en
~/.claude/projectsde modo que dos transcripciones tienen el mismo ID, Claude Code muestra este mensaje en lugar de reanudar una de las copias arbitrariamente
- Para una sesión interactiva, abre el selector de sesiones con
claude --resumey presionaCtrl+Apara ampliarlo a todos los proyectos de esta máquina; luego selecciona la sesión - Las sesiones creadas con
claude -po con el Agent SDK no aparecen en el selector, así que vuelve a comprobar el ID con elsession_idque imprimió tu ejecución original
Windows informó un error (EBADF) cuando Claude Code leyó el archivo de transcripción de esta sesión
Reanudaste una sesión en Windows, su archivo de transcripción guardado se abrió normalmente 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:Failed to resume session <session-id>. Un comando claude --resume o claude -p termina con el 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 analiza o intercepta lecturas de archivos, como herramientas de seguridad, cifrado o administración de endpoints. Las transcripciones se encuentran en
%USERPROFILE%\.claude\projectspor defecto, o en el directorio que indiqueCLAUDE_CONFIG_DIR - Si no puedes agregar una exclusión, agrega Claude Code a las aplicaciones permitidas de ese software
- Vuelve a reanudar la sesió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.
No se puede cambiar de renderizador en esta sesión
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 vuelve a ejecutar/tui fullscreeno/tui defaultCannot 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
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-sourcesy--permission-prompt-toolpermission rules set for this session only: una actualización de permisos de un hook o de un llamador del SDK agregó reglas de denegación o de consulta con el destinosession. Las reglas de permiso limitadas a la sesión no provocan el rechazo. Un reinicio las descarta, y Claude Code vuelve a pedir permiso en su lugarask-before-running rules with no command-line form: una actualización de permisos de un hook o de un llamador del SDK agregó reglas de consulta junto con las reglas que Claude Code vuelve a pasar como--allowed-toolsy--disallowed-tools. No existe ningún flag para las reglas de consultapermission rules a command line cannot carry intactyadded 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 transmitir su texto como el mismo valor
- En una sesión iniciada sin esas restricciones, ejecuta
/tui fullscreen, o/tui defaultpara volver al anterior. Claude Code guarda allí el ajustetui
Can’t restart while work is running or Remote Control is connected
Claude Code no se reinició, y tu sesión sigue ejecutándose como estaba. Sigue la solución que indica el mensaje.Claude Code couldn’t restart
Cuando este mensaje dice que tu conversación está guardada, la conversación está en el disco y puedes retomarla donde se detuvo. Claude Code se estaba reiniciando a sí mismo, por ejemplo para activar o desactivar el renderizado de pantalla completa después de que ejecutaste/tui, y no pudo iniciar el nuevo proceso, así que salió con el estado 1:
/tui fue tu primera entrada en una sesión nueva, el mensaje dice Claude Code couldn't restart. Start Claude Code again.
Qué hacer:
- Vuelve a ejecutar
claudeen tu shell. Si el mensaje decía que tu conversación está guardada, ejecuta/resumeen la nueva sesión y selecciona la conversación. Si no está en la lista, amplía el selector de sesiones - Si los reinicios siguen fallando, inicia Claude Code desde tu shell con
claude --debug-file claude-debug.log. Si falla un reinicio desde esa sesión,claude-debug.log, en el directorio desde el que la iniciaste, registra una líneaFailed to relaunch:con el error del sistema operativo. Incluye esa línea cuando informes el problema
No se pudo abrir Claude Desktop
Ejecutaste/desktop o su alias /app en una sesión, o claude --desktop en tu shell, y falló el comando del sistema que Claude Code usa para abrir Claude Desktop. Después de /desktop, la sesión permanece en la terminal; claude --desktop imprime el mensaje sin el prefijo Error: y termina con el 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:
- Abre Claude Desktop tú mismo y luego vuelve a ejecutar
/desktopoclaude --desktop - Para leer la salida de error completa del comando que falló, activa el registro de depuración con
/debugy vuelve a ejecutar/desktop, o ejecutaclaude --desktop --debug-file <path>, y luego revisa el registro de depuración
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ó sin cambios tu keymap de Zed
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 read your Zed keymap, so it was left unchanged.: Claude Code no pudo leer el archivo, por ejemplo debido a los permisos del archivoYour Zed keymap isn't a readable list of keybindings, so it was left unchanged.: el archivo se leyó correctamente, pero no se interpreta como un array de bloques de atajos de teclado, incluso permitiendo comentarios//y comas finalesCouldn't back up your Zed keymap; not modifying it.: Claude Code no pudo copiar el archivo a una copia de seguridad.bakjunto a él, así que no cambió nadaCouldn'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 atajo de teclado con una clave duplicada puede causar esto
- 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 vuelve a ejecutar/terminal-setup
/terminal-setup no podía interpretar un keymap de Zed que usara comentarios // o comas finales, y reemplazaba todo el archivo 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 Ingresar prompts de varias líneas.
Los informes de uso de skills no están disponibles en esta conexión
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 responde con este mensaje en su lugar:
- Ejecuta
/skill-doctoren la terminal de la máquina donde se ejecuta la sesión, o ejecuta allíclaude -p "/skill-doctor"
Los estilos de salida personalizados no se pueden seleccionar a través de Remote Control
Ejecutaste/output-style desde la aplicación móvil o la web a través de Remote Control, o el comando llegó en un mensaje retransmitido a la sesión. Como ese turno puede no provenir del propietario de la cuenta, Claude Code solo lista y selecciona estilos integrados en él, y agrega este aviso cada vez que el comando lista los estilos o no reconoce el nombre que proporcionaste. El nombre de un estilo personalizado recibe la misma respuesta que un nombre que no existe:
- Elige un estilo integrado, por ejemplo
/output-style concise - Para usar un estilo personalizado, establece
outputStyleen el archivo.claude/settings.local.jsondel proyecto, o ejecuta/output-style <style>en la propia terminal de la sesión si tiene una
Los estilos de salida se guardan en la configuración local, que esta sesión no carga
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 esa sesión nunca vuelve a leer, así que Claude Code se niega en lugar de escribir un ajuste que no tendría efecto:
- Agrega
locala las fuentes de configuración de la sesión y vuelve a cambiar de estilo - Establece la clave
outputStyleen un archivo de configuración que la sesión sí cargue, como.claude/settings.jsonen el proyecto o~/.claude/settings.json. En el SDK de TypeScript, estableceoutputStyledentro del objetosettingsen línea; consulta Activar un estilo de salida
/recap solo se ejecuta cuando lo pides tú mismo
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 tarea programada en la nube 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 proviene de la persona cuya cuenta ejecuta la sesión, así que responde con este aviso en lugar de un resumen:
/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
/recapallí: 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 tarea programada en la nube u otro programa, quita
/recapde ese prompt
/feedback is disabled by your organization’s policy
Este mensaje significa que los comentarios sobre el producto están desactivados, así que el comando que escribiste no abre el cuadro de diálogo de comentarios. Tanto una política de la organización como un rechazo anterior producen el mensaje:- Política de la organización: la política de tu organización no permite enviar comentarios sobre el producto desde Claude Code.
/feedback,/bugy/shareresponden todos con el mensaje. - Rechazo anterior: el servicio de comentarios rechazó un informe que enviaste, por ejemplo con
Couldn't send feedback: Feedback has not been enabled for your organization.A partir de entonces,/feedbacky/bugpueden responder con el mensaje. Dura siete días desde ese rechazo en esta máquina. Esto se aplica en todos los planes, incluidos Pro y Max.
- Para informar un error, abre un issue en github.com/anthropics/claude-code/issues. Cualquier persona puede leer los issues allí, así que omite el código, las transcripciones y cualquier otra cosa confidencial.
- Después de un rechazo anterior, espera a que pasen los siete días y luego vuelve a enviar un informe para ver si el servicio todavía lo rechaza
/feedback is disabled by your organization's policy. Contact your organization admin to enable it.
Errores de plugins
Estos errores provienen de la configuración de plugins y marketplaces. Para problemas de plugins que no producen uno de los mensajes de esta página, como una URL de marketplace que no carga o un plugin que se instala pero no aparece, consulta Solución de problemas de plugins.plugin eval is currently in early access
Ejecutasteclaude plugin eval o claude plugin eval init y terminó con código 1 mostrando uno de estos mensajes antes de hacer nada:
- Ejecuta
claude --version, luegoclaude update, y vuelve a ejecutar el comando en una sesión nueva. Consulta los requisitos para las evaluaciones de plugins - Si ves el segundo mensaje en una compilación actual, vuelve a intentarlo más tarde después de otro
claude update
Marketplace is registered from an untrusted source
El marketplace está registrado con un nombre que está reservado para los marketplaces oficiales de Anthropic, pero su origen registrado no es un repositorio de GitHub deanthropics. Claude Code vuelve a comprobar 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 la v2.1.205, una entrada registrada antes de que su nombre quedara reservado seguía cargándose.
can only be used with GitHub sources from the 'anthropics' organization. claude plugin marketplace add ejecuta la misma comprobación y rechaza un nombre reservado con Failed to add marketplace: seguido de la misma oración sobre el nombre reservado.
Qué hacer:
- Si el marketplace ya está registrado, ejecuta
claude plugin marketplace remove <name>y luego agrégalo de nuevo desde el repositorio oficialgithub.com/anthropics - Si publicas un marketplace de terceros que usaba el nombre antes de que quedara reservado, cámbiale el nombre y pide a los usuarios que lo vuelvan a agregar desde tu origen
- Consulta la lista de nombres reservados en Esquema del marketplace
El nombre del marketplace es otra grafía de un nombre reservado
El nombre del marketplace no es en sí un nombre reservado, pero Claude Code lo trata como otra grafía de uno. Nombres reservados enumera qué grafías cuentan como un nombre reservado. Claude Code rechaza ese nombre cuando agregas el marketplace:/plugin, claude plugin install y claude plugin update advierten:
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:
- Cambia el nombre del marketplace por uno que no escriba un nombre reservado y agrégalo de nuevo
- Para la advertencia de entrada ignorada, ejecuta el comando
claude plugin marketplace removeque indica, o elimina la entrada de~/.claude/plugins/known_marketplaces.json
Claude Code refuses the marketplace name
El nombre de un marketplace registrado suplanta a un marketplace oficial de Anthropic según las reglas que enumera esa sección. Si un marketplace se registró con ese nombre antes de que la comprobación lo bloqueara, el marketplace y los plugins instalados desde él dejan de cargarse, porque Claude Code comprueba el nombre cada vez que lee el catálogo del marketplace. Cuando el nombre imita a uno oficial,claude plugin list y la pestaña Errors de /plugin informan cada plugin afectado con un mensaje que comienza así:
Claude Code refuses this marketplace's name: it looks like one of Anthropic's own. claude plugin marketplace add rechaza cualquier nombre que suplante a uno oficial con Marketplace name impersonates an official Anthropic/Claude marketplace.
Antes de la v2.1.282, claude plugin list y /plugin también informaban que los plugins de un nombre imitador no se habían podido cargar, sin señalar el nombre del marketplace como la causa.
Qué hacer:
- Para conservar un marketplace que un archivo de configuración declara en línea con
"source": "settings", cámbiale el nombre antes de eliminar el nombre anterior, porque eliminar el marketplace también borra su entrada de tus archivos de configuración. Claude Code v2.1.292 o posterior enumera estos pasos en el mensaje:- En cada archivo de configuración que incluya el marketplace en
extraKnownMarketplaces, asigna a la clave de la entrada y a susource.nameun mismo nombre nuevo en ASCII simple que no parezca uno oficial. Si un administrador agrega el marketplace mediante la configuración administrada de tu organización, el administrador se encarga de este paso - Ejecuta
claude plugin marketplace remove <old-name>, o elimina el nombre anterior en la pestaña Marketplaces de/plugin. Esto también desinstala sus plugins y borra sus datos, opciones y secretos - Inicia Claude Code de nuevo, en la carpeta del proyecto si el archivo es el archivo de configuración de un proyecto. Luego instala los plugins desde el marketplace renombrado
- En cada archivo de configuración que incluya el marketplace en
- Para conservar cualquier otro marketplace, espera a que su mantenedor le cambie el nombre y luego ejecuta
claude plugin marketplace update <name> - Para eliminar el marketplace, ejecuta
claude plugin marketplace remove <name>. Esto también desinstala los plugins instalados desde el marketplace y borra sus datos, opciones y secretos - Si publicas el marketplace, cámbiale el nombre en tu
marketplace.json; así los usuarios actualizan el marketplace en lugar de eliminarlo
Marketplace is already added from a different source
Indicaste un nuevo origen de marketplace con--marketplace <source> en el comando de instalación, en una sesión o desde tu shell. El catálogo que Claude Code obtuvo de ese origen tiene el mismo nombre que un marketplace que ya agregaste desde un origen diferente. Claude Code conserva el marketplace existente en lugar de reemplazarlo, y el plugin no se instala.
- Si el marketplace que ya agregaste es el que quieres, instala desde él por nombre:
/plugin install <plugin>@<name> - Para cambiar al nuevo origen, ejecuta
/plugin marketplace remove <name>y luego reintenta la instalación
Un comando de plugin hace referencia a user_config en un comando de shell
Un comando de hook, monitor oheadersHelper de MCP de un plugin hace referencia a una opción del 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 allí como código, así que Claude Code se niega a iniciar el componente en lugar de sustituir el valor. La comprobación se ejecuta sobre la plantilla del comando, por lo que el error aparece incluso cuando todavía no hay ningún valor configurado. Antes de la v2.1.207, el valor se sustituía en el comando de shell.
La redacción depende de qué superficie hizo referencia a la opción. Un hook en forma de shell informa:
headersHelper de MCP informa:
- Para un hook, agrega un arreglo
argspara que se ejecute en forma exec, donde cada${user_config.KEY}se convierte en un argumento sin un shell de por medio. O quita la referencia y lee la variable de entorno$CLAUDE_PLUGIN_OPTION_<KEY>dentro del script - Para un monitor, quita la referencia y haz que el script del monitor lea el valor desde un archivo de configuración
- Para un
headersHelper, mueve${user_config.KEY}al campoheadersdel servidor, que no es analizado por el shell, o lee el valor dentro del script auxiliar
Plugin archive integrity check failed
La entrada del plugin en el marketplace usa un origenarchive con un valor fijado sha256, y el resumen del archivo descargado no coincide con ese valor. Claude Code rechaza la instalación, así que nada cambia en la caché de plugins. La discrepancia tiene tres causas posibles:
- El archivo en la URL cambió después de que el autor calculó el valor fijado
- El autor ingresó un resumen incorrecto en la entrada del marketplace
- La URL sirve un archivo distinto del que el autor fijó
- Si publicas el plugin, vuelve a calcular el resumen del archivo exacto que sirve la URL, por ejemplo con
shasum -a 256 my-plugin.zip, oGet-FileHash -Algorithm SHA256 my-plugin.zipen PowerShell, y actualiza elsha256en la entrada del marketplace - Si instalas el plugin, ejecuta
/plugin marketplace update <name>para actualizar el catálogo por si la entrada se corrigió, y luego reintenta la instalación - Si los resúmenes siguen sin coincidir después de la actualización, pregunta al propietario del marketplace qué archivo fijó antes de instalar
Path escapes plugin directory
Una de las rutas de componentes del plugin lleva fuera del directorio del plugin o no se pudo confirmar que esté dentro de él, así que Claude Code descarta esa ruta y carga el resto del plugin. Para una ruta que el plugin declara enplugin.json o en su entrada del marketplace, el nombre del componente en el mensaje, como commands o hooks, indica el campo que declaró la ruta.
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 lleva fuera del plugin y que no está permitido por las reglas de enlaces simbólicos del marketplace. Para un enlace simbólico, el mensaje también indica adónde se resuelve la ruta:
hooks/hooks.json, significa que Claude Code omitió ese archivo. Cuando Claude Code no puede confirmar que el archivo está dentro del plugin, o dentro de su marketplace en el caso de un plugin en un marketplace local, omite el archivo. El mensaje informa estos archivos con el nombre de componente indicado:
hooks/hooks.json:hooksmonitors/monitors.json:monitorsSKILL.mden la raíz del plugin:skills
hooks/hooks.json que se resuelve fuera tanto del plugin como de su marketplace local:
commands declarada en una entrada del marketplace incluso cuando apuntaba fuera del directorio del plugin.
Antes de la v2.1.257, la comprobación de las rutas que declara el plugin solo miraba cómo estaba escrita la ruta, no adónde lleva un enlace simbólico.
Qué hacer:
- Si instalaste el plugin y no lo mantienes, informa el mensaje a su autor
- Para una ruta que declara el plugin, mueve el archivo referenciado dentro del directorio del plugin y haz que la ruta apunte a él con una ruta relativa
./ - Si la ruta, o una carpeta superior a ella dentro del plugin, es un enlace simbólico que lleva fuera del plugin, reemplaza el enlace simbólico por una copia de aquello a lo que apunta
- Si el mensaje dice que una ruta que declara el plugin contiene una barra invertida, escribe la ruta con barras diagonales, por ejemplo
./commands/deploy.md - Si el mensaje termina con
EACCES, restablece tu permiso de ejecución en cada directorio que lleva al archivo o carpeta que indica la ruta. Revisa los directorios por encima de la ruta, luego sigue cada enlace simbólico que encuentres y revisa los directorios que llevan adonde apunta. Para cualquier otro código de error, búscalo en las causas y pasos para una ruta que no se pudo comprobar. - Para compartir archivos con otros plugins del mismo marketplace, vincúlalos con un enlace simbólico dentro del directorio del plugin, siguiendo las reglas de enlaces simbólicos
No se leyó la ruta del archivo de servidor
El mensajepath not read significa que Claude Code no leyó un archivo de servidor MCP o LSP que un plugin indica, debido a la ruta del archivo. El resto del plugin se carga, sin los servidores que define el archivo.
Una parte .. cuenta incluso cuando la ruta permanece dentro del plugin, como en este ejemplo:
- Si instalaste el plugin y no lo mantienes, informa el mensaje a su autor
- Si mantienes el plugin, conserva el archivo de servidor dentro del directorio del plugin. Indícalo en el manifiesto o en la entrada del marketplace con una ruta que comience con
./y no tenga.., por ejemplo./servers/x.json - Para compartir un archivo de servidor entre plugins del mismo marketplace, vincula el archivo en cada plugin con un enlace simbólico, siguiendo las reglas de enlaces simbólicos
Plugin not loaded: its manifest was not read
Claude Code no pudo confirmar que el manifiesto de un plugin de marketplace en.claude-plugin/plugin.json esté dentro del plugin, así que no carga nada de ese plugin. Para un plugin en un marketplace local, Claude Code tampoco pudo confirmar que el manifiesto esté dentro de ese marketplace. El mensaje aparece en la pestaña Errors de /plugin, y el motivo al final indica lo que encontró Claude Code.
Por ejemplo, este mensaje corresponde a un plugin en un marketplace local cuya carpeta .claude-plugin es un enlace simbólico que lleva fuera del marketplace:
- Si el motivo termina con
EACCES, restablece tu permiso de ejecución en cada directorio que lleva al manifiesto. Revisa los directorios por encima del manifiesto, luego sigue cada enlace simbólico que encuentres y revisa los directorios que llevan adonde apunta. Para cualquier otro código de error, búscalo en las causas y pasos para una ruta que no se pudo comprobar. - Si mantienes el plugin y el motivo indica adónde se resuelve el manifiesto, la carpeta
.claude-plugino el propioplugin.jsones un enlace simbólico que lleva allí. Reemplaza ese enlace por una copia de aquello a lo que apunta. - Si instalaste el plugin y no lo mantienes, informa el mensaje a su autor
La ruta no se pudo comprobar
Claude Code preguntó al sistema operativo si existe una ruta del plugin y obtuvo un error distinto de “no encontrado”, así que no carga lo que indica la ruta. Cuánto del plugin se carga depende de qué ruta falló:- Una de las ubicaciones predeterminadas de componentes de un plugin, como la carpeta
skills/, el archivomonitors/monitors.jsono unSKILL.mden la raíz del plugin: los demás componentes del plugin se siguen cargando - El propio directorio del plugin: no se carga nada de ese plugin
/plugin, el error aparece bajo el plugin e indica la ruta y el código que devolvió el sistema operativo:
claude plugin list, el mismo error dice Path not found: /home/user/my-plugin/skills (skills, ELOOP).
Entre las causas que producen este error están:
ELOOP: un enlace simbólico en la ruta apunta a sí mismo o forma un bucleEIOoESTALE: la ruta está en un montaje de red roto u obsoletoEACCES: uno de los directorios por encima de la ruta te niega el permiso para recorrerlo
- Reemplaza un enlace simbólico que apunta a sí mismo por una carpeta real, o elimínalo
- Si la ruta está en un montaje de red, vuelve a montar el recurso compartido
- Si el código es
EACCES, restablece tu permiso de ejecución en los directorios por encima de la ruta - Ejecuta
/reload-pluginsdespués de corregir la ruta, o reinicia Claude Code, para cargar el plugin o componente
La ruta de la entrada del marketplace no permanece dentro del directorio del marketplace
La entrada del marketplace del plugin declara una ruta de origen que Claude Code no puede resolver a una ubicación dentro del propio directorio del marketplace, así que el plugin no se instala ni se carga. El rechazo abarca:- Una ruta de entrada que es absoluta, sale 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 parte después del
./inicial - Una entrada en un marketplace obtenido desde un origen remoto, como git o una URL, que llega a 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, así que no existen archivos locales del plugin que la ruta pueda indicar. Consulta Los plugins con rutas relativas fallan en marketplaces basados en URL
claude plugin install informa el rechazo así:
claude plugin list muestra el plugin como failed to load con:
- Si mantienes el marketplace, escribe el
sourcede la entrada como una ruta relativa simple con barras diagonales, como./plugins/my-plugin, y mantén cualquier enlace simbólico que atraviese apuntando dentro del directorio del marketplace - Si agregaste el marketplace desde una URL directa, las entradas relativas no se pueden resolver. Pide al autor del marketplace que use otro origen de plugin, o agrega el marketplace desde su repositorio git
Failed to load marketplace configuration
Claude Code guarda los marketplaces de plugins que agregaste 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 existe, pero no es JSON válido o no se puede leer. Un archivo vacío también falla de esta manera.Marketplace configuration file is corrupted: el archivo es JSON válido, pero su contenido no coincide con el esquema del registro.
claude plugin install informa:
claude plugin install no informaba este fallo.
Qué hacer:
- Abre
~/.claude/plugins/known_marketplaces.jsony repara el JSON, o corrige las entradas que el mensaje indica que no coinciden con el esquema del registro - Si no puedes repararlo, elimina el archivo o reemplaza su contenido por
{}, y luego vuelve a agregar cada marketplace conclaude plugin marketplace add <source>. Claude Code vuelve a registrar los marketplaces que tu configuración de usuario o tu configuración administrada declaran enextraKnownMarketplacesla próxima vez que lo inicies en una carpeta en la que hayas confiado.
El plugin es obligatorio en tu organización
Ejecutasteclaude plugin disable, o usaste la pestaña Installed de /plugin, para desactivar un plugin sincronizado desde claude.ai que tu organización marca como obligatorio:
- Pide a un administrador de tu organización de claude.ai que cambie el estado de obligatorio del plugin en claude.ai
El plugin no se desinstaló
Ejecutasteclaude plugin uninstall, o elegiste Uninstall en la pestaña Installed de /plugin, y la desinstalación se detuvo con un mensaje que comienza con "<plugin>" was not uninstalled:. Si el texto después de esos dos puntos comienza con installed_plugins.json en lugar de indicar 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, consulta installed_plugins.json contiene un registro que esta versión no puede leer.
Cuando Claude Code eliminó la entrada del plugin de enabledPlugins y volvió a leer los archivos de configuración de ese alcance, o bien el plugin seguía activado allí, o bien un archivo que podía activarlo no se pudo leer ni comprobar. Borrar las opciones, los secretos y los datos guardados del plugin mientras una entrada de configuración podía volver a activarlo los haría perder, así que la desinstalación se detiene: el plugin sigue instalado y no se borra nada de lo que guardó.
it is still switched on in <file>, although the settings change reported no error: la escritura de la configuración informó éxito, pero la entrada sigue ahí cuando se vuelve a leer el archivoit is still switched on in <file>, and the settings change failed (<error>): el archivo no se pudo guardar, por el motivo 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, así que todavía podría 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.claudeque lo contiene, es un enlace que lleva a una ubicación de red, o porque no pudo examinar esa ruta
claude plugin uninstall termina con código 1, y con --json el resultado incluye failureCode: "settings_still_on". /plugin muestra el mismo mensaje.
Qué hacer:
- Sigue la última oración del mensaje: repara o reemplaza el archivo de configuración que indica, o elimina tú mismo la entrada del plugin de
enabledPluginsen ese archivo, y luego vuelve a ejecutar la desinstalación
Skipping connection (recent failure cached; retries automatically in 15 min, or edit the plugin config to retry now)
Este mensaje significa que Claude Code no inició un servidor MCP proporcionado por un plugin de tipo stdio, porque una conexión a ese servidor falló hace menos de 15 minutos:claude -p al menos 15 minutos después de la conexión fallida más reciente, Claude Code vuelve a intentar conectarse al servidor.
Qué hacer:
Para que Claude Code vuelva a intentar conectarse al servidor sin esperar:
- En una sesión interactiva: ejecuta
/mcp, selecciona el servidor y selecciona Reconnect - En una aplicación de Agent SDK: llama a
reconnectMcpServer()en TypeScript o aClaudeSDKClient.reconnect_mcp_server()en Python con el nombre del servidor - En
claude -p: inicia una sesión interactiva que cargue el mismo plugin, en la misma máquina y con la misma cuenta del sistema operativo y el mismo valor deCLAUDE_CONFIG_DIRque tus ejecuciones. Vuelve a conectar el servidor allí desde/mcp. Una vez que se conecte, Claude Code intenta la conexión en tu próxima ejecución. - Si estás desarrollando el plugin: cambia el
command, losargso elenvdel servidor en el.mcp.jsono elplugin.jsondel plugin. Claude Code intenta la conexión en la siguiente sesión o ejecución declaude -pque cargue la entrada modificada.
Errores de herramientas
Estos errores provienen de las llamadas a herramientas de Claude. Claude corrige por sí solo la mayoría de los errores de herramientas. Cuando alguno necesita un cambio de tu parte, la lista Qué hacer de ese error indica qué debes cambiar.No such tool available
Claude llamó a una herramienta con un nombre que no está en la lista de herramientas de la sesión. Claude Code devuelve el error a Claude como resultado de la llamada a herramienta, y el turno continúa. Cuando Claude Code puede determinar por qué falta la herramienta, agrega una oración después del nombre de la herramienta que da el motivo o nombra la herramienta que se debe llamar en su lugar, como en la segunda línea:- Si ocurre una vez, no necesitas hacer nada. Claude lee el error y el turno continúa.
- Si las llamadas a las herramientas de un servidor MCP siguen fallando con este error, ejecuta
/mcpen la sesión oclaude mcp listen tu shell para revisar el estado del servidor, y vuelve a conectar un servidor con fallas desde/mcp. En el Agent SDK, consulta Manejo de errores.
MCP server connection closed before the tool call was answered
Una llamada a herramienta a un servidor MCP HTTP o a un conector de claude.ai perdió su conexión antes de que el servidor respondiera, así que Claude Code no puede saber si la herramienta se ejecutó:- Verifica en el servicio sobre el que actúa la herramienta si la acción ocurrió, por ejemplo si existe el issue o el registro que debía crear
- Si la acción ocurrió, no vuelvas a ejecutar la herramienta. Claude recibió este mensaje en lugar del resultado de la herramienta, así que infórmale a Claude el resultado.
- Si la acción no ocurrió, pídele a Claude que vuelva a ejecutar la herramienta. No necesitas volver a conectar el servidor antes, porque Claude Code se conecta a él de nuevo para la siguiente llamada a una de sus herramientas. Si esa conexión también falla, consulta Desconexiones de un servidor remoto a mitad de la sesión.
- Si tú desarrollas el servidor y la herramienta se puede llamar dos veces de forma segura, márcala como segura para repetir para que Claude Code pueda repetir una llamada perdida
MCP server is disabled
Este mensaje en un resultado de herramienta significa que Claude llamó a una herramienta de un servidor MCP que está desactivado. Claude Code no se conectó al servidor, así que la herramienta no se ejecutó, y Claude recibió este texto en lugar de un resultado:- Si querías desactivar el servidor, no necesitas hacer nada
- Si Claude necesita las herramientas del servidor, vuelve a activarlo desde
/mcpen el prompt de Claude Code - En una aplicación del Agent SDK, vuelve a activar el servidor llamando a
toggleMcpServer()en TypeScript conenabledestablecido entrue, o atoggle_mcp_server()en Python conenabledestablecido enTrue
MCP tool call timed out with the server’s question unanswered
En modo no interactivo, un servidor MCP solicitó información mediante elicitation durante una llamada a herramienta, y se agotó el límite de tiempo de la llamada antes de que llegara una respuesta:timed out after <N>s y no decía nada sobre la pregunta.
Qué hacer:
- Configura un hook
Elicitationque responda las solicitudes del servidor - En una aplicación del Agent SDK de TypeScript, haz que tu callback
onElicitationdevuelva su respuesta antes de que se agote el límite - Para darle más tiempo a una respuesta, establece un
timeoutmás largo en milisegundos en la entrada de configuración del servidor, como"timeout": 600000para 10 minutos - Ejecuta la tarea en una sesión interactiva en su lugar y responde tú mismo el diálogo del servidor
Permission prompt tool returned an invalid result
La herramienta que pasaste a--permission-prompt-tool devolvió una respuesta que Claude Code no pudo leer, así que la llamada a herramienta que esperaba esa respuesta no se ejecutó, aunque la respuesta permitiera la llamada:
- Devuelve un solo bloque de texto cuyo texto sea
{"behavior": "allow"}o{"behavior": "deny", "message": "<reason>"}. Para cambiar la entrada, agregaupdatedInputal objetoallow. Desde la v2.1.86 hasta la v2.1.206, unallownecesitaba"updatedInput": {}para conservar la entrada. - No devuelvas
structuredContent, que tu SDK de MCP puede agregar por sí solo. Por ejemplo, registra la herramienta:FastMCPoMCPServerdemcp.server: constructured_output=FalseFastMCPdefastmcp: conoutput_schema=None, y devuelve una cadena- SDK de TypeScript de MCP: sin
outputSchema
- Si el error aparece solo con entradas de unos 40 KB o más, no copies la entrada en
updatedInputni en elmessagede una denegación. Para cambiar una entrada tan grande, aumenta el límite de salida de tu herramienta de prompt.
Agent would be spawned with zero tools
Ninguna entrada de la listatools del subagente coincidió con una herramienta utilizable, así que Claude Code se negó a iniciar el subagente: sin herramientas, no podría actuar. El mensaje agrupa tus entradas según lo que salió mal:
- Unrecognized: la entrada no coincide con ningún nombre de herramienta, normalmente por un error tipográfico como
Grpeen lugar deGrep. - Not available to subagents: la entrada nombra una herramienta real que los subagentes no pueden usar. Los subagentes en segundo plano conservan un conjunto más reducido de herramientas integradas, así que una entrada que solo puede usar un subagente en primer plano cae aquí cuando el subagente se ejecutaría en segundo plano, que es el comportamiento predeterminado. Si incluyes
Agent, el mensaje lo reporta en el siguiente grupo. - Matched no tools in this session: la entrada es válida, pero ninguna herramienta de la sesión actual coincide con ella en este momento, como
mcp__github__*sin un servidor MCP de GitHub conectado, oAgentpara un subagente que está en el límite de profundidad.
tools nunca provoca este rechazo. Si dejas vacía la lista tools, o si disallowedTools elimina todas sus entradas, Claude Code también omite el rechazo e inicia el subagente sin herramientas.
Antes de la v2.1.208, el subagente se iniciaba sin herramientas y podía devolver un resultado vacío o confuso.
- Corrige cada entrada que nombra el error comparándola con las herramientas disponibles para subagentes
- Elimina las entradas de herramientas que la sesión no tiene, como herramientas MCP de un servidor que no está conectado
- Si la entrada nombra un servidor MCP conectado, compara la entrada con el nombre de ese servidor tal como lo escriben los nombres de herramientas del servidor, como
reports__v2enmcp__reports__v2__get_totals. Para ese servidor, escribemcp__reports__v2__*, que esmcp__seguido del nombre completo y__*. Con elmcp__reportsmás corto, que nombra un servidor llamadoreports, el subagente no recibe ninguna de las herramientas dereports__v2 - Para una herramienta que los subagentes en segundo plano descartan, como
CronCreate, elimina la entrada - Para conservar en cambio una herramienta como
CronCreate, deja que Claude espere al subagente, ya que un subagente al que Claude espera se ejecuta en primer plano y conserva la herramienta. Si la definición establecebackground: true, elimina primero ese campo, porque mantiene al subagente en segundo plano - Elimina el campo
toolsen lugar de listar herramientas para darle al subagente todas las herramientas disponibles para subagentes - Para una lista
toolsque contiene soloAgent, aumenta el límite de profundidad o dale al agente al menos otra herramienta: Claude Code no proporcionaAgenten ese límite, así que una lista sin nada más se resuelve en ninguna herramienta
File is covered by a Read deny rule
Se llamó a la herramienta Edit o Write sobre una ruta que coincide con una regla de denegación deRead, incluida la creación de un archivo nuevo en esa ruta. Ambas herramientas modifican contenido que Claude tiene que poder volver a leer, así que Claude Code rechaza la llamada antes de cualquier acceso al archivo. NotebookEdit no está cubierta por las reglas de denegación de Read. Antes de la v2.1.228, la regla bloqueaba solo la herramienta Edit, y antes de la v2.1.208, solo una regla de denegación de Edit bloqueaba las ediciones.
and cannot be written.
Qué hacer:
- Si Claude debería poder modificar el archivo, elimina o restringe la regla de denegación de
Readen/permissionso en la configuración - Si el archivo debe permanecer intacto, conserva la regla y agrega una regla de denegación de
Editpara la misma ruta para bloquear también la herramienta NotebookEdit
Setting blocks writes outside the working directories
Cuando Claude intenta escribir un archivo y la llamada a herramienta falla con este mensaje, la ruta está fuera de los directorios de trabajo de la sesión ypermissions.blockWritesOutsideWorkingDirectories está activado:
- Si Claude no debería escribir ahí, no hagas nada
- Para permitir que Claude escriba en un directorio existente que contiene la ruta, ejecuta
/add-dir <directory>en el prompt de Claude Code, o pasa--add-dir <directory>al iniciar Claude Code - Si la ruta es un archivo de configuración de Claude Code, como
~/.claude/settings.json, edítalo tú mismo. Agregar su directorio con/add-dirno sirve, porque entonces Claude Code rechaza la escritura por tratarse de un archivo de configuración. - Para mantener un directorio con permiso de escritura en todas las sesiones, inclúyelo en
permissions.additionalDirectoriesen tu configuración de usuario o en la configuración administrada - Para desactivar
permissions.blockWritesOutsideWorkingDirectories, elimínalo de todos los archivos de configuración que lo establecen y luego reinicia Claude Code - Si ninguno de tus archivos de configuración tiene
permissions.blockWritesOutsideWorkingDirectories, puede provenir de--settingso de una aplicación anfitriona. Claude Code también rechaza estas escrituras mientras no puede leerpermissionsen tu configuración administrada. Consulta a quien inicia o administra la sesión.
Writes to Claude Code settings files are blocked
Cuando Claude intenta escribir un archivo y la llamada a herramienta falla con este mensaje, Claude Code trata el archivo como uno de sus archivos de configuración ypermissions.blockWritesOutsideWorkingDirectories está activado:
- Para cambiar un ajuste, edita tú mismo el archivo de configuración
- Para permitir que Claude vuelva a editar archivos de configuración, elimina
permissions.blockWritesOutsideWorkingDirectoriesde todos los archivos de configuración que lo establecen y luego reinicia Claude Code - Si el archivo no es uno de tus archivos de configuración, búscalo entre los demás archivos que Claude Code trata como archivos de configuración:
- Un archivo que pasaste a
--agentso--mcp-config: edítalo tú mismo - La copia almacenada de la configuración administrada por el servidor y los archivos que se guardan con ella: pídele a un Owner que cambie el ajuste en la configuración administrada por el servidor.
- Cualquier archivo
.json, mientras Claude Code no puede determinar a dónde lleva la carpetamanaged-settings.d/: pídele a tu administrador que revise esa carpeta
- Un archivo que pasaste a
Path cannot contain null bytes
El argumento de ruta o patrón de una llamada a una herramienta de archivos contenía un byte nulo, que los sistemas de archivos y las 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:- Nada de tu parte: el error se devuelve a Claude como resultado de la herramienta, y el propio mensaje le indica a Claude que elimine el byte nulo y lo intente de nuevo
Path contains null bytes, y la herramienta nunca se ejecutaba.
Command contains an invisible character
La herramienta PowerShell se negó a ejecutar un comando que contiene U+FEFF o U+180E:- Para un comando que escribió Claude: no tienes nada que corregir. El mensaje le indica a Claude cómo reescribir el comando.
- Para un archivo de skill o de comando: el mensaje aparece después de
No shell command in <name> was run. Consulta dónde encontrar el carácter y eliminarlo.
Approved command was not run after Claude Code restarted
Un comando de shell que aprobaste no se ejecutó, y Claude recibe este mensaje como resultado del comando:It does not keep track of that directory across a restart in a session that has been in a worktree.
Qué hacer:
- Deja que Claude continúe, y responde la solicitud si se te pide que vuelvas a aprobar el comando.
File is too large to read as an image
Claude intentó leer un archivo como imagen con la herramienta Read, y el archivo supera los 128 MB, el máximo que Read carga de un archivo de imagen. No se leyó nada, y Claude recibe este error como resultado de la herramienta:- Si Claude siguió el mensaje
File is too largey pasó a redimensionar la imagen o a leer una copia más pequeña, no hagas nada - Si Claude se detuvo en el error, exporta tú mismo una copia de menos de 128 MB, por ejemplo con una resolución menor, y dirige a Claude a ese archivo
- Si la ruta era una tubería o un dispositivo, dirige a Claude a un archivo de imagen normal en su lugar
subagent_type is required
subagent_type, y esta sesión no tiene un subagente de propósito general al cual recurrir. Ese es el caso en dos configuraciones:
CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1está establecida en modo no interactivo, lo que elimina todos los subagentes integrados- El agente del hilo principal de la sesión tiene una lista de permitidos
tools: Agent(...)que excluyegeneral-purpose
- Normalmente nada: el mensaje lista los subagentes que sí tiene la sesión, así que Claude puede reintentar con uno de ellos
- Si Claude sigue fallando, agrega
general-purposea la lista de permitidostools: Agent(...), o eliminaCLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS
Agent type 'general-purpose' not found.
Memory index is over its read limit
Claude escribió en el índice de memoria automáticaMEMORY.md y lo dejó por encima de uno de sus límites de lectura: 200 líneas o 25KB. La escritura se completó, pero solo las primeras 200 líneas o 25KB, lo que ocurra primero, se cargan al inicio de una sesión, así que todo lo que supera el límite se descarta cada vez que se lee el índice. Antes de la v2.1.210, un índice que superaba el límite se truncaba silenciosamente en la siguiente carga sin ninguna señal al momento de escribir.
- Deja que Claude reescriba
MEMORY.md, o pídeselo: mantener una línea por entrada, mover los detalles a archivos de temas y combinar o eliminar las entradas obsoletas - Para recortar el índice tú mismo, consulta Auditar y editar tu memoria
pkill pattern matches the Claude Code process
Un comandopkill en una llamada a la herramienta Bash usó un patrón, normalmente con -f, que coincide con el propio proceso de Claude Code, así que Claude Code rechaza el comando en lugar de dejar que termine la sesión. Claude Code prueba el patrón con pgrep antes de ejecutar pkill y lo rechaza cuando su propio ID de proceso aparece en el resultado. La verificación se ejecuta solo en Linux; en macOS, pkill se ejecuta sin modificaciones. Antes de la v2.1.214, el comando se ejecutaba, y un patrón coincidente terminaba la sesión de Claude Code a mitad del turno.
- Restringe el patrón para que coincida solo con el proceso deseado, por ejemplo la ruta completa del binario objetivo en lugar de una subcadena corta
- Para detener procesos iniciados por el shell actual, usa
pkill -P $$con el patrón, lo que limita la coincidencia a los procesos hijos del propio 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 en~/.claude/teams/{team-name}/inboxes/, así que el destinatario no recibió nada. La escritura falla cuando Claude Code no puede crear ni actualizar el archivo, por ejemplo porque el disco está lleno, el directorio no admite escritura u otro agente retiene el bloqueo del buzón durante demasiado tiempo. Antes de la 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 aviso en tu terminal, y su texto le indica a Claude que lo intente de nuevo:
Failed to write the <message> to <name>'s inbox — nothing was sent. El plan approval de esa lista es la decisión del líder que aprueba el plan de un compañero de equipo; el envío del plan por parte del compañero es el mensaje separado plan approval request. Ese mensaje y otros dos mensajes de protocolo tienen su propio texto y consecuencia:
Failed to write the plan approval request to the lead's inbox — plan not submitted; try again: el plan del compañero de equipo nunca llegó al líder, y el compañero permanece en modo plan hasta que un nuevo envío tenga éxitoThe permission request could not be delivered to the team lead (mailbox write failed): la solicitud de permiso del compañero de equipo nunca llegó al líder, así que nadie aprobó la llamada a herramientaThe confirmation could not be written to team-lead's inbox.: la aprobación del apagado sí surtió efecto y el compañero de equipo termina; solo falta la confirmación al líder
@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 conserva tu texto en el cuadro del prompt para que puedas enviarlo de nuevo.
Qué hacer:
- Pídele al remitente que vuelva a enviar el mensaje; la contención por el bloqueo del buzón es transitoria y se resuelve al reintentar
- Revisa el espacio libre en disco y verifica que tu usuario pueda escribir en
~/.claude/teamsy en los archivos que contiene
Teammate’s agent definition was not restored
Claude le 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 a partir de la cual se creó. El aviso sigue al reporte de reanudación en el resultado de la herramienta del agente remitente y nombra el motivo. Cuando el archivo de definición proviene de una carpeta sin confianza guardada, dice:.claude/agents/ del proyecto o de un directorio de --add-dir, y aceptar el diálogo de confianza para una carpeta superior no la satisface.
Qué hacer:
- Ejecuta
claudeen la carpeta que nombra el registro de depuración y acepta el diálogo de confianza. La definición se vuelve a aplicar la próxima vez que Claude Code reactive al compañero de equipo; no necesitas reiniciar la sesión del líder - O establece la entrada
hasTrustDialogAcceptedentrueen~/.claude.json, usando exactamente la claveprojects["<path>"]que muestra el registro de depuración
Only a teammate can approve a shutdown request
Claude Code rechazó una aprobación de apagado del equipo de agentes porque la sesión que la envió no se está ejecutando como compañero de equipo. No se envió nada y nada se apagó. El rechazo aparece en el resultado de la herramienta de la sesión remitente:- Si el rechazo apareció en tu sesión del líder, primero verifica si el compañero de equipo ya se apagó desde entonces. El rechazo vuelve a Claude con la instrucción de enviar en su lugar un
shutdown_request, y el turno continúa. En una sesión interactiva del líder,<name> has shut down.aparece cuando el compañero de equipo aprueba una solicitud de apagado. - Si el compañero de equipo sigue ejecutándose, pídele al líder en su prompt que apague al compañero, por ejemplo
Ask the researcher teammate to shut down. Consulta Apagar compañeros de equipo. - Si un antiguo compañero de equipo que reanudaste tú mismo con
claude --resumerecibió este rechazo, no se envió nada. Para terminar esa sesión, ejecuta/exiten su prompt.
A command-line deny rule cannot be handed to a teammate intact
Este mensaje significa que Claude Code no inició un compañero de equipo en panel dividido en tu equipo de agentes. Claude Code pasa las reglas de denegación de línea de comandos del líder a un compañero de equipo en panel dividido a través de la propia línea de comandos del compañero, y se detiene cuando el compañero interpretaría una de ellas de forma distinta:- Ejecuta
/configen la sesión del líder y establece Teammate mode enin-process. Si la fila diceoverriddeny ya muestrain-process, recorre los valores hasta volver a él. Luego pídele a Claude que inicie de nuevo al compañero de equipo. Un compañero de equipo en proceso se ejecuta bajo las reglas de denegación activas del líder. - Las sesiones posteriores que toman
teammateModede tu configuración de usuario también inician compañeros de equipo en proceso, porque/configguarda la elección ahí. Para volver a los paneles divididos en una sesión posterior, establece Teammate mode enauto,tmuxoiterm2, el que usaras antes.
Message too large for cross-session delivery
El mensaje entre sesiones de Claude a otra de tus sesiones en esta máquina era demasiado largo para enviarse. Claude Code lo rechazó, 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 aviso en tu terminal. Nombra ambos tamaños y cómo hacer que el mensaje quepa:- Pídele a Claude que resuma el mensaje, o que ponga el contenido extenso en un archivo y envíe la ruta del archivo
- Pídele a Claude que divida el contenido en varios mensajes más cortos
Too many messages to this session just now
Claude envió una ráfaga rápida de mensajes entre sesiones a una de tus sesiones en esta máquina, y la ráfaga alcanzó lo que acepta el buzón de esa sesión. Claude Code rechazó el 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 aviso en tu terminal:- Normalmente nada: Claude agrupa el contenido restante en un solo mensaje, o espera antes de enviar más
- Si tú mismo provocaste la ráfaga, pídele a Claude que combine lo que queda en un solo mensaje
Cross-session message was dropped at the recipient session’s inbox
Claude envió un mensaje entre sesiones a otra de tus sesiones en esta máquina, y el buzón de esa sesión lo descartó antes de que Claude lo leyera en esa sesión. La línea nombra al destinatario y, cuando el destinatario dio un motivo, agrega el motivo después de un guion:Cross-session messages (12) were dropped. Para saber a qué sesión pertenece una dirección, compárala con la fila Peer address que muestra /status en cada sesión.
Después del guion, la línea da uno o más de estos motivos:
its queue of undelivered peer messages was full: el destinatario ya tenía tantos mensajes no entregados de otras sesiones como permite su colayou 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 solo remitenteit repeated your previous message: el mensaje era idéntico a uno que la sesión remitente le había enviado a este destinatario poco antesa relay loop between sessions was cut: el mensaje continuaba una larga cadena de respuestas que se puede cortar, como una que incluye una sesión fuera de esta máquina
- Da por hecho que el destinatario nunca vio los mensajes descartados. Claude Code le dice lo mismo a Claude, y le indica que incluya todo lo que siga siendo importante en un solo mensaje posterior en lugar de reenviarlo de inmediato
- Si tus sesiones se envían actualizaciones frecuentes entre sí, pídele a Claude que envíe menos mensajes y más grandes, como un informe cuando una sesión termine su trabajo
- Para
a relay loop between sessions was cut, escribe tú mismo la siguiente instrucción en una de las sesiones. Un mensaje que Claude envía en respuesta a tu propio prompt inicia una nueva cadena
Refusing to send a cross-session message
Antes de que Claude Code escriba un mensaje entre sesiones a otra de tus sesiones en esta máquina, verifica que el socket del buzón de la sesión destino sea el endpoint al que se dirigió el mensaje. Cuando una verificación falla, Claude Code rechaza el envío en la sesión remitente, y la sesión destino no recibe nada. Para un mensaje que envía Claude, el rechazo aparece en el resultado de la herramienta de la sesión remitente:Refusing to send: nombra la verificación que falló:
reply target is a symlink: hay un enlace simbólico en la ruta del socket de la sesión destino. Claude Code no entrega a través de él, porque un enlace ahí podría redirigir el mensaje a un endpoint que la sesión destino no creó.cannot vet reply target: Claude Code no pudo inspeccionar la ruta destino en absoluto, por ejemplo porque al leerla falló con un error de permisos.
- Normalmente nada: las verificaciones evitan que un mensaje llegue a un endpoint distinto de la sesión a la que se dirigió, y no se envió nada
- Si
reply target is a symlinkse repite para una sesión, revisa qué creó un enlace en la ruta del socket de esa sesión, que se muestra en su/statusbajoPeer address
Refusing to read, write, or search a path
Claude Code verifica las reglas de permisos de una ruta de archivo y luego vuelve a confirmar esa resolución cuando la herramienta abre el archivo o inicia la búsqueda. Cuando no puede confirmar que la ruta sigue llevando a la ubicación que aprobó la verificación, Claude Code rechaza la operación en lugar de seguirla. El rechazo aparece en el resultado de la herramienta:its symlink resolution changed after permission was checked: un enlace simbólico a lo largo de la ruta, o en la raíz de búsqueda de Grep o Glob, se reemplazó entre la verificación de permisos 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 en la ubicación aprobadawhere 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 hasta una ubicación final en disco, por ejemplo porque los enlaces simbólicos en ella forman un bucleit is a symbolic link. Write to the link's target path instead: hay un enlace simbólico en la propia ubicación de escritura solicitada, por ejemplo unCLAUDE.mdque es un enlace simbólico aAGENTS.md; el mensaje dirige a Claude al destino del enlaceRefusing 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 en un.mcp.jsonque es un enlace simbólicoRefusing to write into symlinked directory: <path>: el directorio que contiene el archivo es en sí un enlace simbólico, por ejemplo el directorio.claude/de un proyecto enlazado a otra ubicacióna path one of its Read deny rules is written through changed while the search was being prepared. Retry.: una regla de denegación deReadpara la búsqueda nombra una ruta que pasa por un enlace simbólico, y ese enlace cambió mientras Claude Code preparaba la búsquedait could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.: la raíz de búsqueda existe pero no se pudo abrir; el código entre paréntesis es el error del sistema operativoits permission check expired before it ran (too many concurrent file operations). Retry.: Claude Code descartó el registro de aprobación ante muchas operaciones de archivos simultáneas antes de que la herramienta lo usara; reintentar ejecuta una nueva verificación de permisosripgrep 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 binariorga una ruta absoluta, así que rechaza las búsquedas fuera del directorio de trabajo en lugar de ejecutar una que tus reglas de denegación no cubren
- Normalmente nada: el rechazo llega a Claude como resultado de la herramienta, y la operación rechazada no se ejecuta
- Si un rechazo por enlace simbólico se repite en una ruta, averigua qué sigue reescribiendo un enlace ahí, como una herramienta de compilación o un observador de archivos, o pídele a Claude que use la ruta resuelta del archivo en lugar de la enlazada
- Si este rechazo aparece para cada archivo mientras Claude Code se ejecuta en Windows dentro de un AppContainer o de un sandbox de token restringido, actualiza a la v2.1.265 o posterior
- Si aparece un rechazo de lectura en macOS para un archivo que nada está reescribiendo, como una captura de pantalla arrastrada al prompt, actualiza a la v2.1.273 o posterior
- Para el rechazo de ripgrep, instala ripgrep con tu gestor de paquetes para que
rgse resuelva en una ruta absoluta enPATH, o mantén las búsquedas dentro del directorio de trabajo
where it leads on disk could not be determined no aparecía.
The search failed, so this is not a “no matches” result
Una búsqueda de Grep o Glob que ejecutó Claude falló antes de devolver algún resultado, así que no se sabe si existen coincidencias. El mensaje que recibe Claude en lugar de los resultados empieza así:- La primera vez que aparece: nada. El mensaje le pide a Claude que primero vuelva a buscar.
- Si Claude dice que las búsquedas están fallando: captura el error de ripgrep para un reporte de error:
- Desde tu shell, inicia una sesión con los mismos flags que la sesión donde fallaron las búsquedas, más
--debug-file claude-debug.log - Envíale a Claude la solicitud que provocó la búsqueda fallida
- Si la búsqueda vuelve a fallar, busca la línea que contiene
rg error (signal=enclaude-debug.log - Incluye esa línea cuando reportes el problema
- Desde tu shell, inicia una sesión con los mismos flags que la sesión donde fallaron las búsquedas, más
Task output swap refused
Claude Code guarda la salida de cada comando de Bash en un archivo dentro de su directorio temporal. Cada vez que abre uno de estos archivos, verifica que la ruta siga llevando al archivo que creó, sin ningún enlace simbólico, enlace duro adicional o directorio movido que la redirija. Este mensaje significa que esa verificación falló, así que Claude Code rechazó la operación en lugar de escribir o leer la salida a través de esa ruta. El mensaje aparece en el resultado de la herramienta Bash:output symlink was re-pointed, output file identity changed y not a regular file reportan todos la misma condición: algo en la ruta de salida o a lo largo de ella ya no es el archivo que creó Claude Code. Solo algunos motivos incluyen una oración To recover:.
Si la verificación falla mientras un comando sigue ejecutándose, Claude Code detiene el comando, y su resultado reporta:
- Actualiza a la v2.1.260 o posterior. Las versiones anteriores a veces mostraban este mensaje cuando no había ningún enlace ni directorio movido
- Reinicia Claude Code con
CLAUDE_CODE_TMPDIRestablecida en un directorio nuevo - O revisa el directorio de tu proyecto dentro del directorio temporal de Claude Code,
/private/tmp/claude-501/-Users-you-my-projecten el mensaje de ejemplo. Si esa ruta es un enlace simbólico, o un directorio que no debería estar ahí, elimina el propio enlace o directorio en lugar del destino del enlace, y reinicia Claude Code - Si el rechazo se repite, hay un proceso que reemplaza, enlaza o elimina entradas dentro del directorio temporal de Claude Code mientras la sesión se ejecuta. Establece
CLAUDE_CODE_TMPDIRen un directorio que nada más administre y reinicia
Disk full or disk quota used up
Libera espacio, inodos o cuota de disco en el volumen que contiene el directorio temporal de Claude Code. Una línea en el resultado de un comando que empieza conDisk full:, Disk quota used up: o Nearly out of inodes: nombra ese directorio.
Claude Code guarda la salida de cada comando de Bash y PowerShell en un archivo dentro de ese directorio. Si no puede crear ese archivo porque el volumen o tu cuota en él está lleno, tu comando no se inicia, y el resultado que lee Claude es:
Disk full:, Disk quota used up: y Nearly out of inodes: aparecen después de un comando que se ejecutó y terminó con un código distinto de cero. Por ejemplo:
- En macOS y Linux, ejecuta
df -h <dir>en tu shell para ver qué volumen contiene el directorio y qué tan lleno está.df -i <dir>muestra cuántos inodos quedan libres.<dir>es el directorio que nombra tu mensaje, como endf -i /tmp/claude-501 Disk full: this computer's volumeodisk is full (ENOSPC): elimina archivos que no necesites en cualquier parte de ese volumenDisk quota used up:,disk quota is used up (EDQUOT)oDisk full: a test write: elimina tus propios archivos en ese volumen, aunque todavía muestre espacio libreNearly out of inodes:: elimina muchos archivos en ese volumen. Cada uno ocupa un inodo sin importar su tamaño, así que lo que importa es su cantidad, no su tamaño- O reinicia Claude Code con
CLAUDE_CODE_TMPDIRestablecida en un directorio de un volumen con espacio - Luego haz que Claude ejecute el comando de nuevo
Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)The filesystem with Claude Code's temp directory <dir>, or your disk quota on it, is full (ENOSPC)Command output was lost: the temp filesystem at <dir> is fullo... is out of inodesThe command was not started: this computer's disk is full (ENOSPC), so the file that captures command output could not be created. Nothing ran., o lo mismo con(EDQUOT). Esta forma no nombra ningún directorio: busca en el volumen que contiene el directorio temporal de tu sistema, como/tmp, o el directorio establecido enCLAUDE_CODE_TMPDIR
ENOSPC: no space left on device, open <path>.output.
git is not installed on this Mac
Este mensaje significa que un paso en Claude Code necesitaba git, y el git que encontró es el sustituto de Apple en/usr/bin/git. Las herramientas para desarrolladores que proporcionan git no están instaladas.
Claude Code no inicia el sustituto y muestra este texto en su lugar, por ejemplo dentro de un mensaje más largo:
- En Terminal, ejecuta
xcode-select --install, completa la instalación que inicia y luego vuelve a intentar lo que estabas haciendo en Claude Code
File is not valid UTF-8
Claude usó la herramienta Edit o NotebookEdit en un archivo cuyos bytes no se decodifican como UTF-8, y Claude Code rechazó el cambio. No se escribió nada, así que el archivo quedó como estaba. Esas herramientas guardan el archivo completo como UTF-8, lo que habría convertido cada byte que no pudieran decodificar en el carácter de reemplazoU+FFFD. El mensaje aparece en el resultado de la herramienta:
- Para mantener el archivo en su codificación actual, deja que Claude haga el cambio con un comando de shell que lea y escriba el archivo en esa codificación, como le indica el mensaje
- Para seguir editando el archivo con la herramienta Edit, conviértelo a UTF-8, o corrige los bytes no válidos en un archivo que debería ser UTF-8, y luego pídele a Claude que vuelva a hacer la edición
U+FFFD. En esas versiones, actualiza Claude Code.
Refusing to apply edits: a hook is configured for file edits in this session
Claude intentó publicar un artefacto con una actualización en un solo paso, un pequeño cambio en el archivo del artefacto incluido en la publicación, y Claude Code lo rechazó. No se publicó nada y el archivo no cambió. El mensaje aparece en el resultado de la herramienta Artifact:PreToolUse o un mod sobre Edit o Write.
Qué hacer:
- Nada, si Claude pasó a editar el archivo y publicarlo
- Si Claude se detuvo en el mensaje, pídele a Claude que edite el archivo y lo publique
- Si el mensaje sigue apareciendo, cierra Claude Code y vuelve a abrirlo
- Si el mensaje vuelve a aparecer incluso después de volver a abrirlo, desactiva las actualizaciones en un solo paso
The source file is not valid UTF-8 text
Claude intentó publicar un artefacto a partir de un archivo cuyos bytes no se decodifican como texto, o cuyo texto ya contiene el carácter de reemplazoU+FFFD, así que Claude Code rechazó la publicación antes de subir nada. El mensaje aparece en el resultado de la herramienta Artifact y nombra la primera posición que hay que corregir:
UTF-16 y aun así te indica que reescribas el archivo como UTF-8. Cuando hay más posiciones después de la nombrada, el mensaje agrega un conteo como (+2 more) después de la posición.
Qué hacer:
- Normalmente nada: Claude reescribe el archivo y lo publica de nuevo
- Si el archivo es uno que escribiste o exportaste tú, guárdalo de nuevo como UTF-8 y reemplaza cada
U+FFFDpor el carácter que perdió una edición, un pegado o una conversión anterior - Para mostrar un
U+FFFDintencional en la página, escríbelo como�en el HTML en lugar del carácter literal
Not published: that file is on a network share
Claude intentó publicar un artefacto a partir de un archivo en una ruta que nombra un host de red:- En Windows, una ruta
\\server\shareque no está dentro de una unidad de red asignada que pasaste al iniciar con--add-dir - En macOS o Linux, una ruta de montaje automático como
/net/<host>/page.html
- Nada, si no necesitas ese archivo exacto: el mensaje le indica a Claude que publique en su lugar un archivo de las carpetas propias de la sesión
- Para publicar ese archivo exacto, cópialo en una carpeta de un disco local y vuelve a pedirlo
- En Windows, para permitir que Claude publique directamente desde el recurso compartido, asígnalo a una letra de unidad y pasa la unidad al iniciar Claude Code. En PowerShell, por ejemplo, ejecuta
net use Z: \\server\sharey luegoclaude --add-dir Z:\. Así Claude puede publicar archivos desde esa unidad. Agregar la unidad a mitad de la sesión con/add-dirno es suficiente. - En macOS o Linux, monta el recurso compartido en un directorio, como uno dentro de
/mnto/Volumes, y publica desde esa ruta en lugar de la ruta de montaje automático
Not published: Claude sent the same content again after a newer version of the artifact turned it away
Esta línea roja bajo una llamada a Artifact significa que Claude Code detuvo una publicación repetida: el artefacto no se actualizó, y no se escribió nada en el archivo desde el que Claude publica. No necesitas hacer nada a menos que Claude se detenga sin publicar. Antes en la sesión, Claude Code rechazó una publicación porque el artefacto tenía una versión más reciente, por ejemplo una que publicó un editor u otra de tus sesiones. El final de la línea indica lo que Claude tiene que hacer a continuación:- Termina con
Claude needs to work from that newer version first: si Claude se detuvo ahí, pídele que obtenga la versión actual del artefacto, incorpore sus cambios y publique de nuevo - Termina con
should go through: si Claude se detuvo ahí, pídele que publique de nuevo
Reading a local file from outside the connected folders in a Cowork session
En una sesión de Cowork que se ejecuta en tu máquina en la aplicación Claude Desktop, Claude nombró un archivo local para un artefacto. Claude Code no pudo confirmar que el archivo sea un archivo simple dentro de las carpetas conectadas de la sesión: la ruta está fuera de esas carpetas, pasa por un enlace simbólico o está escrita de una forma que puede nombrar un archivo distinto del que parece. Leer un archivo así requiere tu aprobación, y en una sesión que no puede mostrarte la tarjeta de aprobación, como una configurada para omitir todas las aprobaciones, Claude Code rechaza la lectura. El rechazo aparece en el resultado de la herramienta Artifact; cuando el archivo no se pudo examinar en absoluto, nombra esa falla en su lugar:- Normalmente nada: el mensaje le indica a Claude que use en su lugar un archivo simple dentro de las carpetas conectadas
- Para incluir ese archivo exacto en el artefacto, cópialo en una de las carpetas conectadas de la sesión como un archivo normal, no como un enlace simbólico, y vuelve a pedirlo
WebFetch cannot fetch localhost
Claude llamó a WebFetch con una URL cuyo nombre de host no tiene punto, comohttp://localhost:3000 o un nombre de intranet simple como http://wiki/. WebFetch rechaza estas URL antes de hacer cualquier solicitud:
- Normalmente nada: el mensaje dirige a Claude a
curla través de la herramienta Bash, que puede llegar a servidores locales y de intranet
Invalid URL.
Claude Code is unable to fetch from a host
WebFetch envía el nombre de host de una URL aapi.anthropic.com antes de solicitar la página, para compararlo con la lista de bloqueo de seguridad de dominios de Anthropic. Este mensaje significa que la verificación respondió que no se puede obtener contenido de ese nombre de host:
WebFetch domain safety check failed
Antes de obtener una URL, WebFetch envía el nombre de host de la URL aapi.anthropic.com para compararlo con la lista de bloqueo de seguridad de dominios de Anthropic. Si la verificación no puede completarse, WebFetch no puede confirmar que el dominio sea seguro, así que no obtiene la página y el resultado de la herramienta incluye en su lugar uno de estos mensajes:
rate-limited: el endpoint de verificación respondió con HTTP429. El mensaje le indica a Claude que continúe sin la página y que lo intente de nuevo como máximo una vez más tarde. Claude Code no almacena en caché una verificación fallida, así que una obtención posterior de ese dominio vuelve a ejecutar la verificación. Si las sesiones en tu red se topan con esto a menudo, puedes omitir la verificación conskipWebFetchPreflight: trueen la configuración.Unable to verify: la solicitud de verificación falló, agotó el tiempo de espera o recibió otro estado de error. Si tu red bloqueaapi.anthropic.com, agrega ese dominio a la lista de dominios permitidos, u omite la verificación conskipWebFetchPreflight: trueen la configuración.
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 la v2.1.285, una verificación limitada por rate limit se reportaba en su lugar con el mensaje Unable to verify.
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:
- 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 enableo/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: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 conCtrl+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
.., comodocs/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:
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, PowerShell o Monitor en una sesión aislada en un worktree, y Claude Code lo rechazó por una de estas razones:- El comando se ejecutaría en el checkout principal o en otro worktree. El mensaje dice que su directorio de trabajo
resolved to the shared checkoutois in a different worktree. - Un comando Bash o Monitor apunta git al checkout principal.
- Claude Code no puede verificar a partir del texto de un comando Bash o Monitor 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.
is isolated in the worktree <path>, but this command, seguido de la razón, como en el caso de un comando cuyo texto Claude Code no pudo verificar:
- Git apuntado al checkout principal, o texto de comando que no se puede verificar: 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 por una expansión en su texto, escribe el valor marcado literalmente 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 que moviste a segundo plano con← o /background y que se detuvo antes de ejecutar un turno propio. Claude Code no pudo encontrar la conversación desde la que la moviste, por lo que la sesión no tiene nada que reanudar. El mensaje termina con el comando claude respawn para esta sesión:
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.
Qué hacer:
- Para iniciar la sesión detenida desde cero, ejecuta
claude respawn <id>con el ID del mensaje, o presionaEnterdos 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/projectspodí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:running in another terminal: un proceso que no es una sesión en segundo plano mantiene la conversación, por ejemplo una ejecución declaude -p, o una terminal donde la reanudaste conclaude --resumeo/resume. La fila también muestraOpen in a terminal.already open in another running Claude session: otra sesión en segundo plano la mantiene.
- Para
running in another terminal: continúa en esa terminal, o sal de ese proceso o deja que termine, y luego inténtalo de nuevo - Para
already open in another running Claude session: usa esa sesión, o detenla y luego inténtalo de nuevo
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:claude attach <id> imprime este texto. En agent view, el pie de página es más corto y termina con ctrl+x removes the row.
Qué hacer:
- Ejecuta
claude rm <id>para eliminar la fila. Cuando se aplica uno de los casos conservados,claude rmconserva 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>
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 rm indica cómo proceder:
The worktree has unpushed commits en su lugar. En agent view, la fila de la sesión muestra not removed con la misma razón.
Qué hacer:
- Para conservar los commits, envíalos con push. Una vez que el push los coloque en una rama de seguimiento remoto, como
origin/claude/fix-login, intenta eliminar la sesión nuevamente. - Si el mensaje ofrece descartar los commits, primero asegúrate de que no necesitas el worktree, los commits ni ningún cambio sin commit. Luego sigue el paso que indica el mensaje: presiona
Ctrl+Xdos veces en la fila de la sesión en agent view, o ejecuta el comandoclaude rm <id> --discard-unpushed <commit>@<worktree-id>que imprimióclaude rm. Si Claude Code se niega de nuevo, sigue el nuevo mensaje. - 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 intenta eliminar la sesión nuevamente
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 no había forma de descartarlos. Aun así puedes eliminar la sesión, perdiendo los cambios sin commit pero conservando la rama y los commits. Ejecuta git worktree remove --force --force <path> con la ruta que imprimió el rechazo y luego claude rm <id>. Git necesita --force dos veces para un worktree bloqueado.
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:claude attach <id> reinicia una sesión ya marcada como fallida por un host muerto, y en caso contrario imprime la causa y sale:
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
Enteren 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 imprimeSession <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
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:claude attach <id> imprime la causa y sale:
- En agent view, presiona
Enternuevamente 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 luegoclaude attach <id> - Para una fila de comando de shell, presiona
Ctrl+Xen agent view o ejecutaclaude 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 ejemploclaude stop en otra terminal. Claude Code mantiene la sesión detenida:
- 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:
/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>.mden el proyecto de la sesión, o en~/.claude/agents/<name>.mdpara 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
Esta sesión se reinició después de que venciera su siguiente activación de /loop
Un/loop de ritmo propio en una sesión en segundo plano se detuvo. El proceso de la sesión terminó mientras el bucle esperaba su siguiente activación, y esa activación venció antes de que se iniciara el siguiente proceso de la sesión. La activación perdida no se dispara con retraso. El aviso indica cuánto retraso tenía la activación cuando la sesión se reinició:
- Para continuar el bucle, responde a la sesión e indícalo, por ejemplo
keep the loop running. Claude lee el aviso junto con tu respuesta y puede programar la siguiente activación - Si ya terminaste con el bucle, no hagas nada. Ya se detuvo
No LLM gateway: a gateway set in your shell isn’t passed to a session opened from another folder
La sesión en segundo plano que muestra este mensaje no está usando tu LLM gateway: no recibió la dirección del gateway, por lo que sus solicitudes fallan. El mensaje aparece en la conversación en lugar de la respuesta de Claude, con el ID y la carpeta de tu sesión ya completados:No LLM gateway: opened from another folder · respawn from ~/project.
Enviaste, despertaste o reiniciaste la sesión desde una carpeta distinta a la que nombra el mensaje, mientras ANTHROPIC_BASE_URL estaba configurado con tu gateway. Para los casos en los que un gateway exportado en el shell sí llega a una sesión en segundo plano, consulta LLM gateway.
Qué hacer:
- Usaste agent view en un proyecto cuya configuración define el gateway: coloca
ANTHROPIC_BASE_URLy su clave de API o token en el bloqueenvde un archivo de configuración. Usa~/.claude/settings.json, o.claude/settings.local.jsonen el propio proyecto de la sesión, ya que una sesión reiniciada con respawn lee ambos. Luego ejecutaclaude respawn <id>en tu shell desde cualquier carpeta. - Exportaste el gateway en tu terminal: en una terminal donde hayas exportado las variables del gateway, haz
cda la carpeta que nombra el mensaje y ejecuta el comandoclaude respawn <id>del mensaje. La sesión se reinicia a partir de su conversación guardada.- El gateway llega a la sesión solo cuando el propio supervisor se inició desde un shell que exportó el mismo gateway. Si no fue así, reinicia el supervisor desde esa terminal como describe Dispatch fails with
Could not resolve authentication methody luego ejecuta de nuevo el comando de respawn.
- El gateway llega a la sesión solo cuando el propio supervisor se inició desde un shell que exportó el mismo gateway. Si no fue así, reinicia el supervisor desde esa terminal como describe Dispatch fails with
Not logged in · Please run /login, sin nombrar la carpeta.
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:
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 ejecutaclaude daemon statusdesde un shell - Después de corregir el valor en el bloque
envde la configuración, reinicia el servicio en segundo plano conclaude daemon stop --anypara 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 comoEUNKNOWN. 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:
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 primeroclaude daemon runen 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 quenpm 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:
/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:
- 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 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 stderrcon código de salida 1, en cada inicio, en Windows:daemon.locknombra 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.locky 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.
- 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 statuspara 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: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
Esta sesión bifurcada no se pudo iniciar
Bifurcaste una sesión de Remote Control desde claude.ai, y Claude Code no pudo terminar de iniciar la sesión en segundo plano que ejecuta la bifurcación en tu máquina. Este aviso aparece en la transcripción de la sesión bifurcada:- Vuelve a la sesión que bifurcaste y bifúrcala de nuevo una vez que la sesión esté inactiva
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: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.
- Ejecuta
claudeen 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í.Subprocess initialization did not complete within 60000ms
Este error significa que un proceso de Claude Code que la extensión de VS Code o una aplicación del Agent SDK inició no informó a tiempo que estaba listo. La extensión o la aplicación entonces lo detuvo. En una conversación de VS Code, el error comienza conClaude Code did not finish starting, por ejemplo:
Subprocess initialization did not complete within y el límite de tiempo, y luego indica lo que Claude Code informó, por ejemplo:
- Para volver a intentarlo en VS Code, envía un mensaje. Si el error apareció mientras iniciabas sesión, selecciona de nuevo el método de inicio de sesión.
- Para ver hasta dónde llegó Claude Code, haz clic en View output logs debajo del error de una conversación, o ejecuta Claude Code: Show Logs desde la Command Palette. Incluye las entradas alrededor de la línea
Subprocess initializational informar el problema. - Para revisar tu red, consulta Configuración de red. Si el mensaje te indica que revises tu inicio de sesión o autenticación, consulta Inicio de sesión y autenticación.
- Si el mensaje dice que los hooks SessionStart o Setup no habían terminado, comprueba cuánto tardan los tuyos. En VS Code, los primeros 10 minutos en los que Claude Code informa que estos hooks se están ejecutando no cuentan para el límite de 60 segundos. Haz que un hook lento termine antes, reduce el
timeoutde un hook no asíncrono o elimina el hook. - Si tu aplicación del Agent SDK llama a
startup(), estableceinitializeTimeoutMscon un valor suficiente para todo el inicio, o déjalo sin establecer para que no cuenten hasta 10 minutos de tiempo de hooks informado.
Subprocess initialization did not complete within 60000ms — check authentication and network connectivity. Si ves ese texto, actualiza la extensión o el SDK.
El proceso de Claude Code salió con código N
El procesoclaude 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.
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 View output logs 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
claudeen 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 doctoren 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 ejecutableclaude instalado en PATH. La extensión se niega a iniciar Claude Code hasta que encuentre el claude instalado en PATH.
- 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.
The Claude Code program for this computer could not be found
La extensión de VS Code buscó la copia de Claude Code incluida en ella y no encontró ninguna compilada para tu computadora. El mensaje indica la compilación que necesita tu computadora:- Si el mensaje indica qué compilación contiene la extensión, tienes el paquete de la extensión para otra plataforma: instala el paquete hecho para la compilación que indica el mensaje
- Si el mensaje no indica qué compilación contiene la extensión, reinstala la extensión de Claude Code desde la vista Extensions de tu editor
- O, en cualquiera de los dos casos, configura
claudeCode.claudeProcessWrappercon un binarioclaudeinstalado por separado
Unsupported platform: <platform>-<arch>. No compatible Claude Code binary found.
La conexión a Claude Code terminó antes de que este mensaje se completara
La extensión de VS Code envió su mensaje al procesoclaude, 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:
- Envíe el mensaje de nuevo. El siguiente mensaje inicia un nuevo proceso
claudeque reanuda la conversación. - Si se repite, ejecute
claudeen 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
/rewind escribía y eliminaba a través de enlaces en rutas rastreadas, y no informaba de una restauración parcial.
- 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>.txtnombra cada ruta omitida mientras se ejecuta la restauración, así que active el registro de depuración con/debugantes de su próxima restauración. En macOS o Linux, puede encontrar los enlaces directamente:find . -type lpara enlaces simbólicos yfind . -type f -links +1para 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.
/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
/rewindnuevamente 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
/rewindnuevamente. - Para mantener las copias de seguridad más tiempo en futuras sesiones, aumente
cleanupPeriodDays.
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:- 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
--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 paraEDQUOT; restaure el acceso de escritura a la ubicación de la transcripción paraEACCES,EPERM, oEROFS - 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ó conCLAUDE_CODE_SKIP_PROMPT_HISTORY configurado, por lo que Claude Code no escribe transcripción ni historial de indicaciones para ella:
- 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 estableceCLAUDE_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:
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=1configurado. 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_SESSIONde su entorno
Advertencias de configuración
Para encontrar una advertencia que Claude Code mostró al iniciar una sesión interactiva, busca primero debajo del banner de inicio y luego en el registro de depuración:- Fila debajo del banner de inicio: algunas advertencias sobre reglas de permisos, como
⚠ Deny rule Bsh matches no tool · check for typos - Registro de depuración: Claude Code conserva este registro solo en modo de depuración. Para leer las advertencias que contiene, inicia Claude Code desde tu shell con
claude --debug-file <path>y luego abre el archivo en esa ruta.
Claude Code exited after an unrecoverable interface error
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 dos renderizadores. La segunda oración aparece solo cuando el error ocurrió mientras se iniciaba el renderizador de pantalla completa:- Inicia Claude Code de nuevo. Para retomar la conversación, ejecuta
claude --resumeen el mismo directorio. - Si el mensaje menciona el renderizador de pantalla completa, Renderizado de pantalla completa explica qué hace el siguiente inicio, lo cual depende de cómo activaste la pantalla completa, y cómo volver a probar la pantalla completa o mantener el renderizador clásico.
Agent descriptions are over the 15.0k-token limit
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 tus subagentes, excepto los integrados, superan los 15,000 tokens según la estimación de Claude Code. Cada agente cuenta su nombre más su frontmatterdescription. Claude Code carga todos los agentes tanto si el total supera el límite como si no, por lo que la advertencia no cambia lo que se carga.
- Acorta el frontmatter
descriptionde tus archivos de agentes, o pídele a Claude que los recorte por ti. - Elimina los archivos de agentes que ya no uses.
Hook needs quotes around a path with a space
Esta notificación en la vista de conversación significa que el script de un hook no se ejecutó porque su ruta tiene un espacio y no está entre comillas. Ese hook es un hookasyncRewake en forma de shell. En su command, un intérprete como python3 va seguido de un marcador de posición de ruta sin comillas, y la ruta resuelta contiene un espacio.
La notificación comienza con el nombre del evento del hook y menciona el script:
- En el
commanddel hook que ejecuta el script que menciona la notificación, encierra la ruta entre comillas dobles. En un archivo JSON, escríbelo como"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check.py\"".
Instruction file not loaded
Este aviso en la vista de conversación de una sesión interactiva significa que un archivo de memoria que existe no se cargó. Hay una restricción de lectura en vigor.a Read deny rule covers it: una regla de denegación deReadcoincide con la ruta del archivo tal como está escrita o con el destino al que lleva un enlace en ellait's read from outside your working directories, where reads are blocked: el archivo se resuelve fuera de los directorios de trabajo mientraspermissions.blockReadsOutsideWorkingDirectoriesestá activadowhere it leads couldn't be worked out: por ejemplo, el archivo es un enlace que lleva de vuelta a sí mismo, directamente o a través de otros enlaces
and 3 more instruction files not loaded.
Qué hacer:
- Nada, si la restricción es intencional: la sesión se ejecuta sin las instrucciones de ese archivo.
- Para cargar un archivo retenido porque
a Read deny rule covers it, elimina o restringe esa regla. Luego inicia una nueva sesión. - Para cargar un archivo retenido porque
it's read from outside your working directories, where reads are blocked, mueve el archivo, o el destino de su enlace, dentro de los directorios de trabajo. Luego inicia una nueva sesión. - Para cargar un archivo retenido porque
where it leads couldn't be worked out, comprueba si el archivo es un enlace que lleva de vuelta a sí mismo. Si lo es, haz que el enlace apunte a un archivo que exista o coloca un archivo normal en su lugar. Luego inicia una nueva sesión.
Un skill, comando o flujo de trabajo no se cargó porque su nombre está reservado
Una carpeta de skill, unname del frontmatter, un archivo o subcarpeta en .claude/commands/, o un flujo de trabajo guardado usa el nombre anthropic-skills o un nombre que comienza con anthropic-skills:. Claude Code reserva ese nombre para los skills sincronizados 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:
name: que editar o un flujo de trabajo que renombrar. Cuando se rechazó más de un elemento, el aviso termina con un conteo como · 2 more, y el registro de depuración nombra cada uno.
Qué hacer:
- Renombra el elemento que indica el aviso, o edita la línea
name:a la que apunta, y luego reinicia la sesión.
Skill or command name refused
Este aviso de inicio significa que Claude Code rechazó el nombre de al menos un skill o comando personalizado, por lo que no se cargó o se cargó sin su camponame:
- No cargado: Claude Code rechazó el nombre con el que se conoce un skill o comando, como el nombre de su directorio o el nombre o la subcarpeta de un archivo de comando. No aparece en el menú
/y Claude no puede invocarlo. Su línea en el registro de depuración dice<name> is not offered. - Campo
nameignorado: Claude Code rechazó elnamedel frontmatter de un skill. El skill se sigue cargando, pero el menú/no muestra el valor denamey escribirlo no invoca el skill. Su línea en el registro de depuración dice<name value> is not shown for <skill>.
- Inicia Claude Code con
claude --debugdesde tu shell y busca[names]en el registro de depuración. Cada nombre que cuenta el aviso tiene una línea allí. La línea representa algunos caracteres ocultos como códigos, como\u{200B}para un espacio de ancho cero, para que puedas ver dónde están. - Elimina los caracteres que no puede contener el nombre de un skill renombrando la carpeta o el archivo o editando la línea
name:, o acorta un nombre que supere los 256 caracteres. Luego reinicia la sesión, a menos que el archivo esté en un directorio en el que Claude Code detecta cambios. Para un skill de un plugin que no escribiste, pídele al autor del plugin que lo renombre.
Workspace has not been trusted
Claude Code encontró reglaspermissions.allow o entradas permissions.additionalDirectories en el .claude/settings.json o .claude/settings.local.json del proyecto y no las aplicó, porque las reglas de permiso de la configuración del proyecto requieren confianza en el espacio de trabajo. El conteo, el nombre del ajuste y el archivo que se menciona en el mensaje varían según tu configuración. Las reglas deny y ask no se ven afectadas.
- Ejecuta
claudeen el directorio y acepta el diálogo de confianza. Reglas de permiso del proyecto y confianza en el espacio de trabajo indica qué carpeta cubre esa aceptación. - En modo no interactivo con
-pno se muestra ningún diálogo. Establece la entradahasTrustDialogAccepteden~/.claude.jsonusando la claveprojectsexacta que imprime el mensaje. - Si el mensaje menciona
.claude/settings.local.jsone iniciaste Claude Code fuera de un repositorio git o en tu directorio home, actualiza a v2.1.200 o posterior. Las versiones 2.1.196 a 2.1.199 trataban tu propio.claude/settings.local.jsoncomo proporcionado por el repositorio en esos espacios de trabajo. En v2.1.207 y posteriores, actualizar no basta fuera de un repositorio git si no has confiado en la carpeta: determinar que una carpeta no está dentro de un repositorio ejecuta git, y Claude Code ejecuta esa comprobación solo después de que aceptas el diálogo de confianza, así que usa el primer paso. Tu directorio home y cualquier otro directorio home de configuración están exentos y no esperan al diálogo. Consulta Reglas de permiso del proyecto y confianza en el espacio de trabajo.
El directorio de trabajo es una ruta de red
Claude Code no agrega rutas de red como directorios de trabajo. Consultar una ruta de red puede contactar al host que nombra, y en Windows ese contacto puede enviarle tus credenciales al host. Por eso, Claude Code rechaza la ruta sin consultarla. Ves este mensaje cuando ejecutas/add-dir con una ruta de red:
--add-dir o en permissions.additionalDirectories, Claude Code se inicia sin ese directorio. En una sesión interactiva no ves el mensaje al iniciar, porque va al registro de depuración junto con las demás advertencias de inicio.
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 hayas iniciado Claude Code desde un directorio dentro del montaje automático de ese host. Las lecturas dentro de ese montaje automático siguen pasando por la comprobación de rutas de red. - Rutas locales que llegan a una ubicación de red a través de un enlace simbólico o una unión (junction)
\\wsl$ no cuentan como rutas de red.
Qué hacer:
- En Windows, asigna el recurso compartido a una letra de unidad y pasa la unidad al iniciar. En PowerShell, por ejemplo, ejecuta
net use Z: \\server\sharey luegoclaude --add-dir Z:\. - En macOS o Linux, monta el recurso compartido en una ruta local y agrega esa ruta en su lugar.
- Si la ruta está en
permissions.additionalDirectories, elimínala del archivo de configuración que la incluye.
Remote managed settings failed to load
Tu sesión cumple los requisitos para la configuración administrada por el servidor, pero Claude Code no pudo obtenerla o no pudo aplicar lo que devolvió el servidor, por lo que muestra esta advertencia en las sesiones interactivas y en la pestaña Code de Claude Desktop. La causa entre paréntesis indica qué falló, comonetwork 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 ninguno de los ajustes que devolvió superó la validación. Antes de v2.1.282, esta causa decía server returned invalid settings.
El resto de la línea indica con qué política se ejecuta la sesión:
- Configuración almacenada en caché de una obtención anterior exitosa: Claude Code ejecuta la sesión con esa política en caché, excepto las variables de entorno retenidas, y la línea dice
using cached policy. - Sin configuración en caché que aplicar: Claude Code ejecuta la sesión sin configuración administrada por el servidor, y la línea dice
no remote policy applied. Por ejemplo, la máquina todavía no ha obtenido la configuración, o la obtuvo por última vez hace más de 24 horas.
Remote managed settings are still loading: la obtención todavía estaba en curso cuando la sesión continuóRemote managed settings did not load: la obtención terminó sin una respuestaRemote managed settings have now loaded: la configuración se cargó después de una de estas advertencias, y el resto de la línea indica si se aplica una política remota
- Actúa según la causa que indica el mensaje: para una causa de red, comprueba que esta máquina pueda acceder a
api.anthropic.com; para una causa de autenticación, comprueba tu inicio de sesión con/status - Para
no setting in the server response could be applied as written, pídele a tu administrador que corrija la configuración en el servidor - Ejecuta
/statusoclaude doctorpara obtener el diagnóstico completo
Claude Code couldn’t load your organization’s settings
Tu sesión no se ha iniciado porque la configuración de tu organización, incluida su configuración administrada por el servidor, tiene que cargarse primero y Claude Code no pudo cargarla. Por ejemplo:Claude Code can't start this session yet, el diálogo se cierra y la sesión se inicia en cuanto se carga la configuración.
En modo no interactivo y en sesiones en segundo plano, Claude Code en cambio imprime el mensaje y se cierra con el estado 1.
Qué hacer:
could not connect, othe reply came from a network proxy, not Anthropic: comprueba tu conexión de red y, en una red corporativa, pídele a TI que permita HTTPS haciaapi.anthropic.com/api/claude_code/policy_limitsyapi.anthropic.com/api/claude_code/settings. Luego selecciona Retry now, o vuelve a ejecutar tu comando.timed out,Anthropic returned an erroroAnthropic asked it to retry shortly: deja que el diálogo reintente, o vuelve a ejecutar tu comando más tarde. Consulta status.anthropic.com si sigue ocurriendo.still loading, ocouldn't verify your sign-in with Anthropic yet: deja que el diálogo reintente, o vuelve a ejecutar tu comando. Si el mensaje sobre el inicio de sesión sigue apareciendo, vuelve a iniciar sesión ejecutandoclaude auth loginen tu shell.Your Claude session has expired: el inicio de sesión almacenado en esta máquina ya no es válido, así que reintentar no servirá. En el diálogo, selecciona Sign in again para cerrar Claude Code; luego, en tu shell, ejecutaclaude auth login, que funciona incluso mientras no se pueden iniciar sesiones.none of the settings the server returned could be applied as written: pídele a tu administrador que corrija la configuración administrada por el servidor de la organización y luego reintenta.
Managed settings were not approved
La configuración administrada por el servidor de tu organización incluye ajustes que necesitan tu aprobación, y rechazaste el diálogo de aprobación de seguridad, por lo que Claude Code se cierra sin aplicarlos:- Inicia Claude Code de nuevo y aprueba el diálogo para continuar con la configuración de tu organización. Un diálogo rechazado no se recuerda, así que vuelve a aparecer en el siguiente inicio.
- Si no estás seguro de algún ajuste que incluye el diálogo, pregúntale a quien mantiene la configuración administrada de tu organización antes de aprobarlo
Managed settings need your approval
La configuración administrada por el servidor de tu organización incluye ajustes que necesitan tu aprobación en el diálogo de aprobación de seguridad. El comandoclaude plugin que ejecutaste no pudo leer del teclado, por lo que no pudo mostrar ese diálogo. Eso ocurre cuando canalizas o rediriges su entrada y, en macOS y Linux, además no puede abrir /dev/tty. El comando se detuvo antes de hacer ningún cambio:
- Ejecuta
claudeen una terminal y aprueba la configuración cuando aparezca el diálogo; luego ejecuta de nuevo el mismo comandoclaude plugin. Claude Code guarda la aprobación y la configuración aprobada en tu directorio de configuración. Si el comando que se detuvo se ejecutó como otro usuario o conCLAUDE_CONFIG_DIRestablecido, ejecutaclaudede la misma manera para que ambos usen el mismo directorio.
Managed settings block the default model
La configuración administrada de tu organización bloquea el modelo al que se resuelve la opción Default y todos los modelos a los que podría descender. Una sesión que se iniciaría con la opción Default se cierra al iniciar en lugar de ejecutar un modelo bloqueado. El mensaje que ves depende del ajuste que lo bloquea. Cuando lo bloquea una listadeniedModels, el mensaje dice:
availableModels con availableModelsMatch establecido en "exact" lo omite, el mensaje dice:
- Si administras la configuración, agrega a
availableModelsun modelo que tus usuarios puedan ejecutar, o restringe las entradas dedeniedModelsque bloquean todos los respaldos. Bloquear modelos o versiones específicos describe cómo desciende la opción Default - Si no la administras, envía el mensaje a tu administrador. Tus propios archivos de configuración no pueden ampliar una lista administrada de
availableModelsodeniedModels
La configuración administrada no permite este proveedor de API
La configuración administrada de tu organización establece una listaallowedProviders, y el proveedor de API de la sesión no está en ella o la sesión usa un endpoint que no está fijado como requiere esa entrada. Claude Code se niega al iniciar, antes de un inicio de sesión o cuando la sesión vuelve a contactar con la API. El mensaje comienza con los proveedores permitidos:
(allowedProviders lists only unrecognized entries) en su lugar.
Qué hacer:
- Sigue los pasos de
To continue:del mensaje - Si administras la configuración, las líneas del mensaje que comienzan con
Admins:indican la entrada que debes agregar o el valor que debes fijar, y la entradaallowedProvidersindica qué bloqueenvde origen puede fijarlo
MCP server is blocked by enterprise managed policy
Seleccionaste Reconnect en un servidor en/mcp, o volviste a activar allí un servidor desactivado, y un ajuste que restringe los servidores MCP bloquea ese servidor. Claude Code se niega a conectarlo y muestra:
- Una entrada de
deniedMcpServersque coincide con el servidor, incluida una en tu propio~/.claude/settings.jsono en el.claude/settings.jsondel proyecto - Una lista
allowedMcpServerscon la que el servidor no coincide strictPluginOnlyCustomizationconmcpbloqueado, lo que bloquea los servidores configurados en~/.claude.jsony.mcp.jsondisableClaudeAiConnectors, cuando el servidor es un conector de claude.ai
- Revisa tus propios archivos de configuración de usuario y de proyecto en busca de uno de estos ajustes y cámbialo o elimínalo
- Si ninguno de tus propios ajustes explica el bloqueo, pregúntale a tu administrador qué ajuste administrado bloquea el servidor
/mcp podían conectar un servidor que una actualización de política a mitad de sesión había bloqueado.
El nombre del servidor MCP está reservado
Este mensaje nombra uno de tus servidores MCP cuyo nombre está entre los que Claude Code reserva, como los nombres de sus servidores integrados:- Renombra el servidor donde lo defines, por ejemplo de
workspaceamy-workspace - Para ver otros nombres reservados que debes evitar, consulta Advertencias de configuración de MCP
Managed settings document could not be parsed
Tu organización despliega configuración administrada, y uno de los documentos desplegados está presente pero no se puede analizar como un objeto JSON, por lo que Claude Code se cierra con el código 1 al iniciar en lugar de ejecutarse sin la política que contiene el documento. La línea nombra el origen que falló antes del mensaje:- La ruta del archivo
managed-settings.jsono de un archivo complementario dentro demanaged-settings.d - El perfil de preferencias administradas de macOS,
per-user managed preferencesodevice-level managed preferences - El valor del registro de Windows,
Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings
claude -p, sesiones del Agent SDK, sesiones en segundo plano y la mayoría de los subcomandos, incluido claude doctor. El rechazo falla de forma cerrada a propósito: los ajustes de un documento que Claude Code no puede analizar no se pueden aplicar, e iniciar de todos modos ejecutaría sesiones sin los controles de la organización.
Un problema de esquema en un documento que se puede analizar no produce este error. Encontrar las entradas que Claude Code descartó explica qué hace Claude Code en ese caso.
Cuando existe un directorio managed-settings.d/ pero no se puede listar, Claude Code informa Managed settings drop-in directory could not be read: seguido del error subyacente. Encontrar las entradas que Claude Code descartó explica cuándo un error de lectura provoca la salida al iniciar.
Qué hacer:
- Si administras la máquina, corrige el documento mencionado para que se analice como un objeto JSON, o elimina el archivo, el perfil o el valor del registro. Un
managed-settings.jsonvacío cuenta como{}y no bloquea el inicio. - Si no la administras, pídele a tu administrador que corrija el documento desplegado. Nada de tus propios archivos de configuración causa ni resuelve este error.
Unable to read managed policy settings
Tu organización despliega configuración administrada, y uno de los orígenes desplegados existe pero no se pudo leer, por un motivo como un error de E/S en lugar de que el sistema operativo deniegue la lectura. Si ningún otro origen de administración proporciona una política, Claude Code se cierra al iniciar en lugar de ejecutarse sin la política que podría contener el origen:claude gateway se rechazan con una variante de la primera línea que menciona allowedProviders.
Una lectura que el sistema operativo denegó, como en un archivo solo para root, no produce esta salida: la sesión se inicia sin las políticas de ese origen. Para un origen que no se puede analizar, Claude Code se cierra con un mensaje diferente que nombra el origen.
Qué hacer:
- Si administras la máquina, corrige el problema que indica la línea
Detail:para que el origen desplegado se pueda leer, o elimina el origen - Si no la administras, envía el mensaje a tu administrador. Nada de tus propios archivos de configuración causa ni resuelve este error
Managed settings contain invalid entries, including PreToolUse/PermissionRequest hooks that are NOT loaded
Este bloque en stderr de una ejecución con-p significa que un origen de configuración administrada contiene una entrada de hook que Claude Code no puede cargar. Ese hook no se ejecuta, y cuando una línea indica que el campo hooks del origen se ignora, no se ejecuta ninguno de los hooks de ese origen.
Cada línea nombra el origen, el campo cuando lo hay y el problema, como un type de hook desconocido o un hook declarado fuera de la clave hooks:
- Si administras el origen, corrige o elimina cada entrada que enumera el bloque. Configuración de hooks muestra la forma que Claude Code espera bajo
hooks. - Si el origen de una línea es
parent managed settings, la aplicación que inició Claude Code pasó esa entrada como configuración principal, así que infórmalo al desarrollador de esa aplicación - De lo contrario, envía el bloque a tu administrador
-p mostraba este caso bajo el encabezado Managed settings failed to load; policies from the failed source are NOT in effect:.
otelHeadersHelper failed
Claude Code muestra esta advertencia como una notificación en la interfaz de terminal, una vez por sesión interactiva, cuando el scriptotelHeadersHelper falla o imprime una salida que no cumple los requisitos del script.
Mientras el script siga fallando, las exportaciones fallan y tu backend de telemetría no recibe nada de la sesión.
El texto después de See /status: indica qué falló, como el código de salida del script seguido de su salida de error:
- Ejecuta
/statuspara leer el detalle del fallo. - Corrige el script para que termine con 0 en menos de 30 segundos e imprima en stdout un objeto JSON con valores de encabezado de tipo cadena. Consulta los requisitos del script.
- Si tu organización despliega el script mediante configuración administrada, pídele a quien la mantiene que lo corrija.
-p, el mismo fallo aparece en stderr como otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error> en su lugar.
headersHelper not run
Claude Code conectó un servidor MCP solo con susheaders estáticos y omitió el headersHelper del servidor, porque el helper es un comando de shell y la carpeta no tiene confianza guardada. Una carpeta obtiene confianza guardada cuando estableces su entrada en ~/.claude.json a mano o, fuera de tu directorio home, cuando aceptas el diálogo de confianza para ella en una sesión interactiva. Consulta Confiar en una carpeta antes de que se ejecute su headersHelper para saber a qué servidores se aplica esta comprobación.
Claude Code escribe esta línea solo en modo no interactivo, una vez por servidor. En una sesión interactiva escribe el mismo rechazo en el registro de depuración.
projects que imprime el mensaje es la carpeta en la que, según Reglas de permiso del proyecto y confianza en el espacio de trabajo, Claude Code basa la confianza. Aceptar el diálogo de confianza para una carpeta principal no satisface la comprobación, y una sesión con -p o del SDK tampoco la satisface.
Qué hacer:
- Ejecuta
claudeen la carpeta que indica el mensaje, acepta el diálogo de confianza y luego ejecuta de nuevo tu comando con-po del SDK - Establece tú mismo la entrada
hasTrustDialogAccepteden~/.claude.json, usando la claveprojectsexacta que imprime el mensaje - Si iniciaste la sesión en tu directorio home, trabaja desde un directorio de proyecto en el que hayas confiado. Cuando aceptas el diálogo de confianza en tu directorio home, Claude Code mantiene esa confianza solo para la sesión actual.
Malformed Tool(content) rule
Una regla de permisos en uno de tus archivos de configuración no tiene la formaTool o Tool(content), por ejemplo porque hay texto después del paréntesis de cierre o falta uno de los paréntesis. Claude Code omite la regla y la incluye en el diálogo de configuración no válida cuando se inicia una sesión interactiva, y en la salida de claude doctor:
- En el archivo de configuración que se indica junto al mensaje, reescribe la regla para que termine en su paréntesis de cierre, por ejemplo
Bash(ls *)en lugar deBash(ls) x - Deja los paréntesis dentro del contenido tal como están. Son literales, así que una regla como
Edit(./Finance (2024)/**)es válida sin escaparlos
Mismatched parentheses.
Matches no tool · check for typos
Esta fila debajo del banner de inicio nombra una regla de permisos de denegación o de consulta cuyo nombre de herramienta Claude Code no reconoce, por lo que la regla no se aplica a la herramienta que querías. Una regla de denegación escrita comoBsh no se aplica a Bash, y tampoco una que usa la etiqueta que muestra una herramienta en la transcripción en lugar de su nombre canónico. La fila repite la regla tal como la escribiste:
- Corrige el nombre de la herramienta en la regla, por ejemplo
Bashen lugar deBsh. Consulta los nombres canónicos en la referencia de herramientas. - Para encontrar dónde está definida la regla, ejecuta
/permissionsen la sesión y selecciona la regla. Sus detalles indican de dónde proviene, comoFrom project local settings, oFrom CLI argumentpara un valor de--disallowedTools. - Si los detalles dicen
From enterprise managed settings, reenvía la fila a quien mantiene tu configuración administrada, ya que no puedes cambiar esa regla tú mismo.
--output-format json o stream-json, Claude Code escribe la advertencia en el registro de depuración en lugar de en stderr. Ejecuta con --debug para capturarla en ~/.claude/debug/<session-id>.txt.
Antes de v2.1.305, una sesión interactiva imprimía la forma más larga en stderr al iniciar en lugar de mostrar la fila.
Is not matched by file permission checks
Claude Code encontró una regla de permisos deWrite, NotebookEdit, MultiEdit o Glob con una ruta en uno de tus archivos de configuración, en la configuración administrada o en el valor de un flag --allowedTools, --disallowedTools o --settings. Comprueba los permisos de archivos solo contra reglas Edit y Read, por lo que nunca consulta una regla de ruta que nombre una de las otras herramientas de archivos. Mantiene la regla y no cambia nada más.
-
Sesión interactiva: la advertencia completa va al registro de depuración, y una regla de denegación o de consulta con esta forma también se muestra como esta fila debajo del banner de inicio:
Una regla de permiso con esta forma no recibe fila. Para encontrar dónde está definida la regla, ejecuta
/permissionsen la sesión y selecciona la regla. -
Modo no interactivo con salida de texto: la advertencia completa en stderr nombra la regla, su origen entre paréntesis y el reemplazo que debes escribir:
-
Sesión en segundo plano, o
--output-format jsonostream-json: la advertencia completa va al registro de depuración en lugar de a stderr, para que la salida que leen las máquinas se mantenga limpia. Ejecuta con--debugpara capturarla en~/.claude/debug/<session-id>.txt.
- Reemplaza las reglas
Write(path),NotebookEdit(path)y las antiguasMultiEdit(path)porEdit(path). Las reglasEditcubren todas las herramientas de edición de archivos. - Excepto en
--allowedTools, donde Claude Code acepta una reglaGlobsin advertencia, reemplaza las reglasGlob(path)porRead(path). - Corrige la regla en su origen, que la advertencia completa indica entre paréntesis: una ruta de archivo de configuración, o el propio flag en el caso de
--allowed-toolsy--disallowed-tools. Una rutaclaude-settings-<hash>.jsonque no existe en el disco representa un valor--settingsen línea. Corrige el JSON que pasas a ese flag. - Deja como están las reglas que solo nombran la herramienta, como
WriteoGlob. Claude Code las aplica a nivel de herramienta y no advierte sobre ellas. - Para una regla de la configuración administrada, los paréntesis de la advertencia completa dicen
managed policy settingsy los detalles de la regla en/permissionsdicenFrom enterprise managed settings. Reenvía esa advertencia a quien mantiene tu configuración administrada, ya que no puedes resolverla tú mismo.
Has a wildcard before the rest of the command
Claude Code encontró una regla de permiso deBash cuyo * aparece antes de una palabra posterior que determina de qué comando se trata, como Bash(git * main) o Bash(git -C * status *), en uno de tus archivos de configuración, en la configuración administrada o en el valor de un flag --allowedTools o --settings. El * coincide con cualquier texto, incluidas las 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. Patrones con comodines muestra las reglas de coincidencia.
La advertencia existe para que puedas restringir una regla cuyo comodín es más amplio de lo que pretendías. Claude Code mantiene la regla y no cambia nada en cómo coincide. En modo no interactivo con salida de texto, la advertencia en stderr nombra la regla y su origen entre paréntesis:
/permissions en la sesión y selecciona la regla.
Qué hacer:
- Reemplaza el
*que está antes del subcomando por el valor exacto que quieres:Bash(git checkout main)en lugar deBash(git * main). - Mueve cada
*después del subcomando:Bash(git status *)en lugar deBash(git -C * status *). Escribe una regla por cada subcomando que quieras permitir. - Corrige la regla en su origen, que la advertencia completa indica entre paréntesis: una ruta de archivo de configuración, o el propio flag
--allowed-tools. Una rutaclaude-settings-<hash>.jsonque no existe en el disco representa un valor--settingsen línea. Corrige el JSON que pasas a ese flag. - Para una regla de la configuración administrada, los paréntesis de la advertencia completa dicen
managed policy settingsy los detalles de la regla en/permissionsdicenFrom enterprise managed settings. Reenvía esa advertencia a quien mantiene tu configuración administrada, ya que no puedes resolverla tú mismo.
--output-format json o stream-json, Claude Code escribe la advertencia en el registro de depuración en lugar de en stderr, para que la salida que leen las máquinas se mantenga limpia. Ejecuta con --debug para capturarla en ~/.claude/debug/<session-id>.txt. Antes de v2.1.246, Claude Code aceptaba estas reglas sin advertencia.
Antes de v2.1.305, una sesión interactiva imprimía la advertencia completa en stderr en lugar de mostrar una fila.
Denying Bash also turns off the PowerShell tool
Eliminaste la herramienta Bash completa, por ejemplo con--disallowedTools Bash o con una regla de denegación Bash o Bash(*) sin más en uno de tus archivos de configuración. En Windows con Git Bash instalado, denegar Bash también desactiva la herramienta PowerShell, por lo que la sesión se inicia sin ninguna herramienta de shell.
En modo no interactivo con salida de texto, Claude Code imprime esta advertencia en stderr al iniciar, y una sesión interactiva la escribe solo en el registro de depuración:
- Para que Claude use PowerShell, establece
CLAUDE_CODE_USE_POWERSHELL_TOOLen1en tu entorno o en el bloqueenvde un archivo de configuración, como muestra Habilitar la herramienta PowerShell. La herramienta PowerShell permanece activada junto con tu regla de denegación de Bash. - Para bloquear comandos concretos en lugar de la herramienta completa, reemplaza la entrada
Bashsin más por reglas acotadas comoBash(git push *)en el mismo archivo de configuración o flag. Claude conserva la herramienta Bash, y la herramienta PowerShell permanece desactivada hasta que también establezcas la variable o agregues una regla de permisos dePowerShellacotada.
--output-format json o stream-json, Claude Code escribe la advertencia en el registro de depuración en lugar de en stderr. Ejecuta con --debug para capturarla en ~/.claude/debug/<session-id>.txt. Antes de v2.1.287, Claude Code desactivaba la herramienta PowerShell de la misma manera sin imprimir ninguna advertencia.
Antes de v2.1.305, una sesión interactiva también imprimía la advertencia en stderr al iniciar.
crossSessionInbound must be one of accept, hold, refuse
Un archivo de configuración establececrossSessionInbound 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, de proyecto, local o de --settings dice:
refuse, el valor más restrictivo, y la advertencia indica que los mensajes entre sesiones se rechazan hasta que un administrador lo corrija. Para saber cómo se combina la retención con los valores de tus otros archivos de configuración, consulta crossSessionInbound.
Qué hacer:
- Establece la clave en
"accept","hold"o"refuse", o elimínala - Cuando la advertencia menciona la configuración administrada, pídele al administrador que corrija el valor
ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name
EstablecisteANTHROPIC_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:
- Establece
ANTHROPIC_FOUNDRY_RESOURCEsolo con el nombre del recurso y reinicia Claude Code. Para el endpointhttps://my-resource.services.ai.azure.com/anthropic, el nombre esmy-resource. - Para indicar en cambio la URL completa del endpoint, establece
ANTHROPIC_FOUNDRY_BASE_URLcon la URL y eliminaANTHROPIC_FOUNDRY_RESOURCE; luego reinicia Claude Code. Claude Code acepta solo una de las dos variables.
The 200K limit isn’t enforced
EstablecisteCLAUDE_CODE_DISABLE_1M_CONTEXT=1, que normalmente hace que la compactación automática limite a una ventana de 200K las sesiones en modelos con contexto de 1M, pero ningún umbral de compactación limita esta sesión a 200K o menos, por lo que la conversación puede crecer más allá de ese límite.
- El ID del modelo no es uno que Claude Code reconozca, como un alias de un gateway de LLM, y estableciste
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1o elevaste la ventana supuesta por encima de 200K conCLAUDE_CODE_MAX_CONTEXT_TOKENS. En este caso, el mensaje también ofreceor update to a Claude Code version that recognizes <model>como solución. - Una beta
context-1msolicitada medianteANTHROPIC_BETASo el flag--betassigue pidiendo a la API la ventana de 1M en un modelo que acepta esa beta, mientras que nada compacta la sesión en 200K
- Establece
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000, o el ajusteautoCompactWindowen200000, para que la compactación automática compacte en el límite de 200K - Si el mensaje nombra un ID de modelo que esta versión no reconoce, ejecuta
claude update. Una versión que reconozca el ID como un modelo con contexto de 1M aplica el límite sin más configuración. - Si en cambio quieres que la sesión use la ventana completa del modelo, elimina
CLAUDE_CODE_DISABLE_1M_CONTEXT; la advertencia solo informa de que el límite de 200K no se aplica
--output-format json o stream-json, va en cambio al registro de depuración. Ejecuta con --debug para capturarla en ~/.claude/debug/<session-id>.txt.
Antes de v2.1.305, una sesión interactiva imprimía la advertencia en stderr al iniciar.
ID de modelo no reconocido en una solicitud
Claude Code envió una solicitud para un ID de modelo que tu versión de Claude Code no reconoce, y no encontró ninguna entrada demodelOverrides que asigne ese ID a un modelo que sí reconozca. Claude Code sigue enviando la solicitud con el ID tal como lo configuraste, y no se cierra ni cambia de modelo.
[claude-code:unrecognized_model]. Después del prefijo y un espacio, Claude Code escribe un objeto JSON de una sola línea. Claude Code puede agregarle campos en una versión posterior, así que ignora cualquier campo que no esperes. Escribe al menos estos dos:
model: la cadena del modelo tal como la configurastequery_source: la ruta de solicitud que usó el modelo. Por ejemplo, el valor essdkpara la conversación principal de una ejecución con-py comienza conagent:para un subagente.
- En modo no interactivo con
-p, Claude Code la escribe en stderr con cualquier--output-format, para que puedas analizar stdout sin filtrar la línea - En una sesión interactiva o en una sesión en segundo plano, Claude Code la escribe en cambio en el registro de depuración; ejecuta con
--debugpara capturarla en~/.claude/debug/<session-id>.txt
us.anthropic.claude-... de Amazon Bedrock, los ID de Agent Platform de Google Cloud con un sufijo de versión @ y los nombres de despliegue de Microsoft Foundry que contienen un ID de modelo de Claude. Claude Code comprueba el modelo que hay detrás de un ARN de perfil de inferencia de aplicación de Amazon Bedrock en lugar del ARN en sí. No escribe ninguna línea para un ARN que no puede resolver, como uno mal escrito.
Qué hacer:
-
Si estableciste el ID a propósito, como un alias de un gateway de LLM, agrega una entrada
modelOverridesa tu archivo de configuración con el ID como valor. Usa un ID de modelo de Anthropic como clave, no un alias de familia comoopus. Paramy-proxy-modelde la línea de ejemplo, agrega esta entrada:Claude Code trata entoncesmy-proxy-modelcomoclaude-opus-4-6y deja de escribir la línea. -
Si el ID nombra un modelo más reciente que tu versión de Claude Code, ejecuta
claude update -
Si el ID es un error tipográfico, corrígelo en cualquiera de los lugares donde puedes establecer un modelo o de las variables de alias que lo contenga. Si
query_sourcecomienza conagent:, corrígelo en cambio donde estableces el modelo del subagente.
Las entradas de permiso del sandbox se ignoran bajo un bloqueo administrado
Esta advertencia en/status y claude doctor significa que la configuración administrada establece allowManagedReadPathsOnly o allowManagedDomainsOnly, por lo que las entradas allowRead o allowedDomains del archivo que menciona no se aplican:
sandbox.network.allowedDomains y allowManagedDomainsOnly, y dice only allowed domains (and WebFetch domain rules) from managed settings are honored.
Qué hacer:
- No tienes que hacer nada con respecto a la advertencia
- Si necesitas esas rutas o dominios y la configuración administrada de tu organización establece el bloqueo, pídele a tu administrador que los agregue a esa configuración. La advertencia permanece hasta que también elimines las entradas del archivo mencionado.
- Para quitar la advertencia, elimina las entradas del archivo mencionado. Para un archivo que compartes, como el
.claude/settings.jsonde un proyecto, puedes dejar las entradas para los compañeros de equipo que no tienen el bloqueo y dejar que la advertencia se siga mostrando.
Sandbox mask files left behind at write-deny paths
Esta advertencia enclaude doctor y /status enumera archivos de máscara: archivos marcadores de posición de 0 bytes y de solo lectura en rutas en las que el sandbox deniega las escrituras. Aparece en Linux y WSL2 cuando el sandboxing está habilitado con el aislamiento del sistema de archivos activado. Elimínalos desde tu shell cuando no haya ninguna sesión de Claude Code abierta en el proyecto que los contiene.
El sandbox crea un marcador de posición mientras se ejecuta un comando en el sandbox y lo elimina cuando el comando termina. Uno queda atrás en casos como estos:
- La sesión se termina a la fuerza antes de que acabe el comando, por ejemplo por SIGKILL
- Sales de la sesión mientras un comando en el sandbox todavía se está ejecutando, como uno en segundo plano
claude doctor, la advertencia dice:
- Sal de todas las sesiones de Claude Code abiertas en el proyecto que contiene los archivos listados, incluida cualquier sesión en la que
/statusmostró la advertencia, y luego trabaja desde tu shell. Un marcador de posición que el sandbox de otra sesión todavía está usando es una parte activa de la protección contra escritura de esa sesión - En tu shell, elimina cada archivo listado con
rm, y confirma sirmpregunta por un archivo protegido contra escritura. La advertencia nombra hasta tres archivos y cuenta el resto, así que vuelve a ejecutarclaude doctordespués de eliminarlos hasta que la advertencia deje de aparecer - Si una elección de permiso que guardaste con “Yes, and don’t ask again” no se conservó, guárdala de nuevo después de eliminar el marcador de posición
Stale sandbox mask files left by a killed session.
Antes de v2.1.257, claude doctor no señalaba estos archivos; las versiones anteriores dejan los mismos marcadores de posición cuando se termina una sesión a la fuerza.
Two Claude Code config files exist
Claude Code está usando el primer archivo que nombra este mensaje, por lo que el contenido del segundo archivo no está en vigor. El primero es.config.json, un nombre anterior de .claude.json. El mensaje incluye una comprobación para saber qué archivo contiene tu configuración:
The one with hasCompletedOnboarding or mcpServers in it is usually yours. reemplaza la oración que contiene el comando grep.
Qué hacer:
1
Encuentra el archivo que contiene tu configuración
- En Windows: abre ambos archivos y comprueba cuál contiene
hasCompletedOnboardingomcpServers - En otras plataformas: en tu shell, ejecuta el comando
grepdel mensaje y comprueba qué archivo tiene el conteo más alto
2
Actualiza todos los hosts que comparten el directorio home
Si varios hosts comparten este directorio home, primero actualiza Claude Code en todos los hosts a la versión que indica el mensaje o a una posterior.
3
Detén Claude Code
Detén tus procesos de Claude Code en todos los hosts.
4
Mueve el archivo que no quieres
Mueve fuera de su carpeta el archivo que no quieres. Muévelo en lugar de eliminarlo, para poder restaurarlo.
5
Espera antes de volver a iniciar Claude Code
No inicies Claude Code en ningún host hasta que ningún host siga mostrando el archivo movido en su ruta anterior.
Make this change again later: ~/.claude.json could not be updated
Este aviso en stderr significa que un cambio en~/.claude.json, como un inicio de sesión o una respuesta a una solicitud de confianza, no se guardó en el archivo:
- Vuelve a hacer el cambio en una sesión posterior. Por ejemplo, ejecuta
/loginde nuevo o vuelve a responder la solicitud de confianza.
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-modelconfigurado 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 los modelos Fable, 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. Aparece un aviso en la transcripción
/model. La configuración del modelo explica cuándo se aplica cada respaldo.
Verifique estos primero:
- Selección de modelo: ejecute
/modelpara confirmar que está en el modelo que espera. Una opción anterior de/modelo una variable de entornoANTHROPIC_MODELpueden tenerlo en un modelo más pequeño del que pretendía. - Nivel de esfuerzo: ejecute
/effortpara 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 atajoultrathink. - Presión de contexto: ejecute
/contextpara ver qué tan llena está la ventana. Si está cerca de la capacidad, ejecute/compacten un punto natural o/clearpara comenzar de nuevo. Consulte Explorar la ventana de contexto para ver cómo auto-compact afecta los turnos anteriores. - Instrucciones obsoletas: los archivos
CLAUDE.mdgrandes u obsoletos y las definiciones de herramientas MCP consumen contexto y pueden dirigir las respuestas. La verificación/doctormarca archivos de memoria de gran tamaño y extensiones no utilizadas, y/contextmuestra el uso de tokens de herramientas MCP. Antes de v2.1.205,/doctorabría una pantalla de diagnósticos que marcaba archivos de memoria de gran tamaño y definiciones de subagentes.
/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
- Ejecute
/feedbackdentro 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,/feedbackguarda un archivo local que puede enviar a su representante de cuenta de Anthropic en su lugar. - Si
/feedbackresponde que está deshabilitado por la política de tu organización, consulta la entrada de ese mensaje - Ejecute
claude doctordesde su shell para un diagnóstico de solo lectura de su instalación, o ejecute la verificación/doctordentro de Claude Code para encontrar y solucionar problemas de configuración - Consulte status.claude.com para incidentes activos
- Busque problemas existentes en GitHub