Solucionar problemas de instalación e inicio de sesión

Corrige errores de comando no encontrado, PATH, permisos, red y autenticación al instalar o iniciar sesión en Claude Code.

Si la instalación falla o no puedes iniciar sesión, encuentra tu error a continuación. Para problemas en tiempo de ejecución después de que Claude Code esté funcionando, consulta Solución de problemas. Para problemas de configuración como ajustes que no se aplican o hooks que no se disparan, consulta Depurar tu configuración.

Encuentra tu error

Haz coincidir el mensaje de error o síntoma que estás viendo con una solución:

Si tu problema no está listado, sigue las verificaciones de diagnóstico a continuación para acotar la causa.

[!TIP]

Si prefieres omitir la terminal por completo, la aplicación de escritorio Claude Code te permite instalar y usar Claude Code a través de una interfaz gráfica. Descárgala para macOS o Windows y comienza a programar sin ninguna configuración de línea de comandos. En Linux, instala la aplicación con apt siguiendo las instrucciones de instalación de Linux.

Ejecuta verificaciones de diagnóstico

Verifica la conectividad de red

El instalador descarga desde downloads.claude.ai. Verifica que puedas alcanzarlo:

[tab] macOS/Linux

curl -sI https://downloads.claude.ai/claude-code-releases/latest

[tab] Windows PowerShell

curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

PowerShell crea un alias de curl a Invoke-WebRequest, que rechaza los flags -sI, así que llama a curl.exe explícitamente.

Alcanzaste el servidor si la primera línea muestra un estado 200. Verás HTTP/2 200 en macOS y Linux, y HTTP/1.1 200 OK desde el curl.exe incluido con Windows. Otros resultados apuntan a la causa:

• 403: generalmente un proxy o filtro de red bloqueando el host, o Claude Code no está disponible en tu región
• 5xx: generalmente un problema temporal del servicio; espera unos minutos y vuelve a intentarlo

Si no ves salida, o el instalador muestra Could not resolve host o se agota el tiempo de espera de la conexión, la conexión falló, así que revisa estas causas:

• Firewalls corporativos o proxies bloqueando downloads.claude.ai
• Restricciones de red regional: intenta una VPN o una red alternativa
• Problemas de TLS/SSL: consulta Errores de conexión TLS o SSL

Si estás detrás de un proxy corporativo, establece HTTPS_PROXY y HTTP_PROXY en la dirección de tu proxy antes de instalar. Pregunta a tu equipo de TI por la URL del proxy si no la conoces, o verifica la configuración del proxy de tu navegador.

Este ejemplo establece ambas variables de proxy y luego ejecuta el instalador a través de tu proxy:

[tab] macOS/Linux

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

[tab] Windows PowerShell

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

Verifica tu PATH

Si la instalación fue exitosa pero obtienes un error command not found o not recognized al ejecutar claude, el directorio de instalación no está en tu PATH. Tu shell busca programas en los directorios listados en PATH, y el instalador coloca claude en ~/.local/bin/claude en macOS/Linux o %USERPROFILE%\.local\bin\claude.exe en Windows.

El instalador detecta este caso y lo informa en Setup notes: en su salida: Native installation exists but ~/.local/bin is not in your PATH. en macOS y Linux, o Native installation exists but C:\Users\you\.local\bin is not in your PATH. en Windows. Imprime la corrección junto con esa nota, pero no modifica el PATH por sí mismo.

[!NOTE]

La extensión de VS Code no coloca claude en esta ubicación. Incluye una copia privada de la CLI dentro del directorio de la extensión para su propio panel de chat y no la agrega a PATH. Si solo has instalado la extensión, ~/.local/bin/claude no existirá. Ejecuta la instalación independiente para usar claude desde una terminal y luego continúa con lo siguiente.

Primero verifica que el programa esté ahí, y luego verifica si su carpeta está en tu PATH. La corrección del PATH es permanente, así que la aplicas una sola vez. Elige la pestaña de tu plataforma y ejecuta sus comandos allí: en tu terminal en macOS y Linux, o en PowerShell o el Símbolo del sistema en Windows.

[tab] macOS/Linux

Verifica que el instalador haya colocado el programa:

ls -la ~/.local/bin/claude

• No such file or directory: no hay una instalación nativa. Si no has instalado Claude Code de otra manera, como con npm, Homebrew o un gestor de paquetes de Linux, instala Claude Code. Si lo instalaste de otra manera, consulta Verifica instalaciones conflictivas.
• Un listado del archivo: el programa está ahí. Verifica tu PATH a continuación.

Lista tus entradas de PATH y filtra por la carpeta de instalación:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

Si esto imprime /Users/you/.local/bin o /home/you/.local/bin, el directorio está en tu PATH y puedes saltar a Verifica instalaciones conflictivas. Si no hay salida, agrégalo a la configuración de tu shell con los dos comandos correspondientes a tu shell. El comando echo guarda el ajuste para cada terminal nueva, y source lo aplica a la ventana en la que estás. El comando echo no imprime nada cuando tiene éxito.

Para Zsh, el predeterminado en macOS:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Para Bash en Linux, donde es el predeterminado en la mayoría de las distribuciones:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Para Bash en macOS, agrega la línea a ~/.bash_profile en su lugar. Terminal en macOS inicia Bash como un shell de inicio de sesión, que ignora ~/.bashrc y lee solo el primero que exista de ~/.bash_profile, ~/.bash_login o ~/.profile. Si ya tienes un ~/.bash_login o ~/.profile y ningún ~/.bash_profile, pon la línea en ese archivo en lugar de crear ~/.bash_profile:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Alternativamente, cierra y vuelve a abrir tu terminal.

Si el comando echo imprime permission denied, consulta permission denied al agregar a tu PATH.

Para otros shells como fish o Nushell, agrega ~/.local/bin a tu PATH usando la sintaxis de configuración propia de tu shell y luego reinicia tu terminal.

Verifica que la corrección funcionó:

claude --version

Si todavía no se encuentra claude, revisa estas causas:

• La terminal es anterior al cambio: una ventana que ya estaba abierta conserva su PATH anterior, y una terminal dentro de un editor toma su PATH del editor. Abre una ventana nueva, o cierra y vuelve a abrir el editor.
• La línea no se guardó: ejecuta grep -n '.local/bin' ~/.zshrc, usando el nombre de archivo de tu shell. Imprime la línea con su número de línea cuando la línea está ahí. Si no imprime nada, ejecuta de nuevo los dos comandos de PATH.
• La línea fue al archivo de otro shell: ejecuta echo $0 para ver tu shell y luego ejecuta los dos comandos de PATH para ese shell.

[tab] Windows PowerShell

Verifica que el instalador haya colocado el programa:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

• False: no hay una instalación nativa. Si no has instalado Claude Code de otra manera, como con npm o WinGet, instala Claude Code. Si lo instalaste de otra manera, consulta Verifica instalaciones conflictivas.
• True: el programa está ahí. Verifica tu PATH a continuación.

Lista tus entradas de PATH y filtra por la carpeta de instalación:

$env:PATH -split ';' | Select-String '\.local\\bin'

Si esto imprime C:\Users\you\.local\bin, el directorio está en tu PATH y puedes saltar a Verifica instalaciones conflictivas. Si no hay salida, agrega el directorio de instalación a tu PATH de usuario:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Reinicia tu terminal para que el cambio surta efecto.

Verifica que la corrección funcionó:

claude --version

Si todavía no se encuentra claude en una terminal nueva, revisa estas causas:

• La terminal se ejecuta dentro de un editor: toma su PATH del editor, así que cierra y vuelve a abrir el editor.
• El cambio no se guardó: ejecuta [Environment]::GetEnvironmentVariable('PATH', 'User') y busca .local\bin en el PATH que imprime. Si falta, ejecuta de nuevo los dos comandos.

[tab] Windows CMD

Verifica que el instalador haya colocado el programa:

dir "%USERPROFILE%\.local\bin\claude.exe"

• File Not Found o The system cannot find the path specified.: no hay una instalación nativa. Si no has instalado Claude Code de otra manera, como con npm o WinGet, instala Claude Code. Si lo instalaste de otra manera, consulta Verifica instalaciones conflictivas.
• Un listado de claude.exe: el programa está ahí. Verifica tu PATH a continuación.

Lista tus entradas de PATH y filtra por la carpeta de instalación:

echo %PATH% | findstr /i "local\bin"

Si no hay salida, abre Configuración del sistema, ve a Variables de entorno y agrega %USERPROFILE%\.local\bin a tu variable PATH de usuario. Reinicia tu terminal.

Verifica que la corrección funcionó:

claude --version

Si todavía no se encuentra claude en una terminal nueva, ten en cuenta que una terminal dentro de un editor toma su PATH del editor, así que cierra y vuelve a abrir también el editor.

Verifica instalaciones conflictivas

Múltiples instalaciones de Claude Code pueden causar desajustes de versión o comportamiento inesperado. Verifica qué está instalado:

[tab] macOS/Linux

Lista todos los binarios claude encontrados en tu PATH:

which -a claude

Si esto imprime claude not found, una línea no claude in, o nada, no hay ningún claude en tu PATH. Las siguientes verificaciones muestran si hay alguno instalado.

Verifica las tres ubicaciones de donde puede venir un binario claude. ~/.local/bin/claude es el instalador nativo, ~/.claude/local/ es una instalación npm local heredada creada por versiones anteriores de Claude Code, y la lista npm global muestra una instalación -g:

ls -la ~/.local/bin/claude

Una instalación nativa muestra un enlace simbólico en ~/.local/share/claude/versions/. Un script o un enlace simbólico que creaste tú mismo en esta ruta es un iniciador personalizado, que la actualización automática deja en su lugar.

Si algún comando ls imprime No such file or directory, eso no es un error. Significa que no hay nada instalado en esa ubicación, así que continúa con la siguiente verificación.

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

Si ls -la ~/.local/bin/claude imprimió No such file or directory, no hay una instalación nativa. Si no has instalado Claude Code de otra manera, como con npm, Homebrew o un gestor de paquetes de Linux, instala Claude Code. Si ~/.local/bin/claude existe pero which -a claude no lo listó, la carpeta no está en tu PATH: consulta Verifica tu PATH.

[tab] Windows PowerShell

Lista todos los binarios claude encontrados en tu PATH:

where.exe claude

Si esto imprime INFO: Could not find files for the given pattern(s)., no hay ningún claude en tu PATH.

Verifica si el instalador nativo colocó un binario:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

• True: la instalación nativa está ahí. Si where.exe no encontró nada, su carpeta no está en tu PATH: consulta Verifica tu PATH.
• False: no hay una instalación nativa. Si no has instalado Claude Code de otra manera, como con npm o WinGet, instala Claude Code.

Si encuentras múltiples instalaciones, mantén solo una. Se recomienda la instalación nativa en ~/.local/bin/claude en macOS/Linux o %USERPROFILE%\.local\bin\claude.exe en Windows. Elimina las adicionales:

Desinstala una instalación npm global:

npm uninstall -g @anthropic-ai/claude-code

Elimina la instalación npm local heredada:

[tab] macOS/Linux

rm -rf ~/.claude/local

[tab] Windows PowerShell

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

Elimina una instalación de Homebrew en macOS. Si instalaste el cask claude-code@latest, sustituye ese nombre:

brew uninstall --cask claude-code

Elimina una instalación de WinGet en Windows:

winget uninstall Anthropic.ClaudeCode

Verifica los permisos de directorio

Una instalación que falla por permisos indica la ruta que no pudo crear o en la que no pudo escribir. En Windows, la instalación escribe dentro de %USERPROFILE%, en el que tu usuario puede escribir de forma predeterminada, por lo que esta sección rara vez se aplica allí.

En macOS y Linux, la instalación escribe en estas ubicaciones:

• ~/.claude/downloads/: donde el comando de instalación coloca el binario descargado
• ~/.local/bin/: el iniciador claude
• ~/.local/share/claude/: cada versión que descarga
• ~/.local/state/claude/: sus archivos de bloqueo
• ~/.cache/claude/: descargas preparadas
• ~/.claude.json: tu archivo de configuración global, donde el instalador registra el método de instalación

Si estableces XDG_DATA_HOME, XDG_STATE_HOME o XDG_CACHE_HOME, la instalación los usa en lugar de ~/.local/share, ~/.local/state y ~/.cache. Si estableces CLAUDE_CONFIG_DIR, el archivo de configuración global se ubica en ese directorio en lugar de tu directorio home.

Verifica si los directorios son escribibles:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

Si algún directorio no es escribible, crea el directorio de instalación y establece tu usuario como propietario:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

Verifica que el binario funciona

Si claude --version imprime una versión pero claude se bloquea o se cuelga al iniciar, ejecuta estas verificaciones para acotar la causa. Si claude --version dice comando no encontrado, ve primero a Verifica tu PATH; los comandos a continuación asumen que claude está en tu PATH.

Confirma que el binario existe y es ejecutable:

[tab] macOS/Linux

ls -la "$(command -v claude)"

[tab] Windows PowerShell

Get-Command claude | Select-Object Source

En Linux, verifica si faltan bibliotecas compartidas. Si ldd muestra bibliotecas faltantes, es posible que debas instalar paquetes del sistema. En Alpine Linux y otras distribuciones basadas en musl, consulta Configuración de Alpine Linux.

ldd "$(command -v claude)" | grep "not found"

Confirma que el binario puede ejecutarse:

claude --version

Problemas comunes de instalación

Estos son los problemas de instalación más frecuentes y sus soluciones.

El script de instalación devuelve HTML en lugar de un script de shell

El comando de instalación falla con uno de estos errores cuando lo que descargó no es el script de instalación.

Bash o Zsh: el error cita la primera línea de la página devuelta.

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell, errores de análisis: los errores apuntan a la página devuelta, con iex intentando ejecutar HTML y CSS como PowerShell.

iex : At line:1 char:2310
+ ... igin="anonymous"/><script type="text/javascript">!function(o,c){var n ...
Missing argument in parameter list.
...

La redacción varía según la versión de PowerShell y el idioma del sistema: puedes ver Missing expression after unary operator '--' o un ParserError con ParseException en su lugar. Las etiquetas HTML o el CSS en el texto citado identifican este fallo. Si descargas con -OutFile install.ps1 en su lugar, el archivo guardado es la misma página web, por lo que eso tampoco ayuda.

PowerShell, System.Xml.XmlDocument: el error nombra este tipo en lugar de citar la página.

System.Xml.XmlDocument : The term 'System.Xml.XmlDocument' is not recognized as the name of a cmdlet, function, script
file, or operable program.

Cuando irm puede analizar la respuesta como XML, devuelve un objeto XML en lugar de texto, y iex luego intenta ejecutar el nombre de tipo de ese objeto como un comando. El script de instalación es código de PowerShell y no se analiza como XML, así que este error también significa que la respuesta fue algo distinto del script. La redacción alrededor del nombre de tipo varía según la versión de PowerShell y el idioma del sistema, pero System.Xml.XmlDocument en sí se mantiene igual, así que búscalo por el nombre de tipo.

CMD: ves este error, seguido del HTML de la página devuelta.

< was unexpected at this time.

C:\Users\you><!DOCTYPE html>...

La primera línea aparece en el idioma de tu sistema, así que busca el HTML que le sigue.

Un 403 sin página: dependiendo de cómo se enrutó la solicitud, curl reporta un estado 403 sin cuerpo HTML.

curl: (22) The requested URL returned error: 403

Todos estos significan que la URL de instalación devolvió una página web, un documento XML o un estado de error en lugar del script de instalación. Si la salida del error cita "App unavailable in region", Claude Code no está disponible en tu país. Consulta países admitidos.

Un 403 sin cuerpo a menudo tiene la misma causa, pero también puede provenir de un proxy corporativo o un firewall que bloquea la descarga. Si estás en un país admitido y aún ves el 403, sigue los pasos de Verifica la conectividad de red antes de intentar los instaladores alternativos a continuación, ya que esos acceden a los mismos hosts.

De lo contrario, esto puede ocurrir debido a problemas de red, enrutamiento regional o una interrupción temporal del servicio.

Soluciones:

1. Reintenta después de unos minutos: el problema suele ser temporal. Espera e intenta el comando original nuevamente.

2. Usa un método de instalación alternativo: a diferencia de una instalación nativa, una instalación con Homebrew o WinGet no se actualiza sola de forma predeterminada.

   En macOS, instala a través de Homebrew:

   brew install --cask claude-code
   

   En Windows, instala a través de WinGet:

   winget install Anthropic.ClaudeCode
   

   Luego ejecuta claude --version para confirmar: el comando imprime un número de versión como 2.1.211 (Claude Code). Si el shell reporta que no se encuentra claude, abre una nueva ventana de terminal e intenta nuevamente: la sesión desde la que instalaste mantiene su antiguo PATH.

command not found: claude después de la instalación

La instalación finalizó pero claude no funciona. El error exacto varía según la plataforma:

En Windows, si el error comenzó justo después de que Claude Code se actualizara, consulta restaurar claude.exe desde su respaldo.

De lo contrario, consulta Verifica tu PATH para la corrección en cada plataforma.

permission denied al agregar a tu PATH

Si el comando echo que agrega ~/.local/bin a tu PATH imprime zsh: permission denied: /Users/you/.zshrc o bash: /home/you/.bashrc: Permission denied, tu usuario no puede escribir en ese archivo y no se guardó nada. En tu terminal, verifica quién es el propietario del archivo, usando el nombre de archivo de tu shell en lugar de ~/.zshrc:

ls -l ~/.zshrc

El tercer campo de la salida es el propietario.

• El propietario es otro usuario, como root: toma la propiedad con sudo chown $(whoami) ~/.zshrc, lo cual requiere derechos de administrador.
• El propietario eres tú: el archivo es de solo lectura. Hazlo escribible con chmod u+w ~/.zshrc.

Luego ejecuta nuevamente los dos comandos de PATH para tu shell en Verifica tu PATH.

curl: (56) Failure writing output to destination

El comando curl ... | bash descarga el script y lo canaliza a Bash para su ejecución. Este error, y el relacionado curl: (23) Failure writing output to destination, significa que Bash no recibió el script completo. El código de salida 56 indica que la descarga en sí fue interrumpida, y el código de salida 23 indica que curl no pudo escribir lo que recibió en la tubería, generalmente porque Bash terminó antes de tiempo.

Prueba que puedas acceder a downloads.claude.ai con la verificación en Verifica la conectividad de red. Si accediste al servidor, el fallo original probablemente fue intermitente; reintenta el comando de instalación. También puedes probar un método de instalación alternativo.

Cask de Homebrew no disponible u obsoleto

Homebrew reporta Error: Cask 'claude-code' is unavailable: No Cask with this name exists cuando tu copia local del índice de casks de Homebrew es anterior a la publicación del cask. Actualiza el índice e intenta nuevamente:

brew update
brew install --cask claude-code

Si Homebrew instala una versión de Claude Code más antigua de la que esperas, el mismo índice obsoleto suele ser la causa. El cask claude-code sigue el canal estable y normalmente está aproximadamente una semana detrás de la última versión; para la versión más reciente ejecuta brew install --cask claude-code@latest en su lugar. Consulta Configurar canal de versión para ver la diferencia entre los dos casks.

Cask 'claude-code@latest' is not installed

Homebrew ofrece dos casks, claude-code y claude-code@latest. Ejecutar brew upgrade --cask claude-code@latest cuando ese cask no es el instalado imprime Error: Cask 'claude-code@latest' is not installed. Para ver qué cask tienes, ejecuta esto en tu terminal:

brew list --cask | grep claude-code

Actualiza el cask que imprime. Si no imprime nada, ninguno de los dos casks está instalado.

Errores de conexión TLS o SSL

Errores como estos significan que el protocolo de enlace TLS falló:

• curl: (35) TLS connect error
• schannel: next InitializeSecurityContext failed
• El Could not create SSL/TLS secure channel de PowerShell
• El Could not establish trust relationship for the SSL/TLS secure channel de PowerShell

Para CRYPT_E_NO_REVOCATION_CHECK o CRYPT_E_REVOCATION_OFFLINE, ve al paso 4.

Soluciones:

1. Actualiza los certificados CA de tu sistema:

   En Ubuntu/Debian:

   sudo apt-get update && sudo apt-get install ca-certificates
   

   En macOS, el curl del sistema usa el almacén de confianza de Keychain; actualizar macOS en sí actualiza los certificados raíz.

2. En Windows PowerShell 5.1, habilita TLS 1.2:

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   

   Luego ejecuta el instalador en la misma ventana:

   irm https://claude.ai/install.ps1 | iex
   

3. Verifica si hay interferencia de un proxy o firewall: los proxies corporativos que realizan inspección TLS pueden causar estos errores, incluidos unable to get local issuer certificate, unable to verify the first certificate y SELF_SIGNED_CERT_IN_CHAIN. Haz que la descarga de instalación confíe en la CA de tu proxy corporativo:

   [tab] macOS/Linux

   Establece CURL_CA_BUNDLE para las descargas con curl del script de instalación, y NODE_EXTRA_CA_CERTS para el comando claude install que el script ejecuta después. Pide a tu equipo de TI un archivo PEM con el certificado CA raíz de tu proxy si no lo tienes. Este ejemplo establece ambas variables en el archivo CA de tu proxy y ejecuta el script en la misma terminal:

   export CURL_CA_BUNDLE=/path/to/corporate-ca.pem
   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
   curl -fsSL https://claude.ai/install.sh | bash
   

   Si la instalación aún falla con uno de esos errores de certificado, pide a tu equipo de TI un archivo que contenga tanto los certificados raíz públicos como la cadena CA completa de tu proxy. Luego establece ambas variables en ese archivo.

   [tab] Windows PowerShell

   El instalador de PowerShell descarga a través de .NET, que valida TLS contra el almacén de certificados de Windows. Pide a tu equipo de TI que agregue el certificado CA del proxy al almacén de Windows si aún no está allí, y luego ejecuta el instalador:

   irm https://claude.ai/install.ps1 | iex
   

   Para Claude Code en sí una vez instalado, establece NODE_EXTRA_CA_CERTS para que las solicitudes de API confíen en el mismo paquete:

   [tab] macOS/Linux

   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
   

   [tab] Windows PowerShell

   $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'
   

4. En Windows, evita las verificaciones de revocación bloqueadas. Los errores CRYPT_E_NO_REVOCATION_CHECK (0x80092012) y CRYPT_E_REVOCATION_OFFLINE (0x80092013) significan que curl accedió al servidor pero tu red bloquea la consulta de revocación de certificados, algo común detrás de firewalls corporativos. Si el comando que falla es el curl que descarga install.cmd, ejecútalo nuevamente desde CMD agregando --ssl-revoke-best-effort:

   curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
   

   Cuando las descargas propias del script encuentran los mismos errores, el script las reintenta automáticamente con verificación de revocación de mejor esfuerzo, por lo que el flag solo es necesario en el comando que ejecutas tú mismo. La verificación de mejor esfuerzo tolera un servidor de revocación inaccesible pero aún rechaza un certificado que se sabe que está revocado, igual que los navegadores manejan la revocación. También puedes evitar por completo la verificación de revocación de curl ejecutando el instalador de PowerShell desde PowerShell, que descarga a través de .NET y no falla cuando el servidor de revocación es inaccesible:

   irm https://claude.ai/install.ps1 | iex
   

   También puedes instalar con winget install Anthropic.ClaudeCode, que evita curl por completo.

Failed to fetch version from downloads.claude.ai

El final del mensaje indica el motivo. Si es un error de certificado como unable to verify the first certificate, consulta Errores de conexión TLS o SSL. Para cualquier otro motivo, consulta Verifica la conectividad de red.

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

La conexión con el servidor de descarga se cerró mientras claude install o claude update obtenía el binario de Claude Code, y los reintentos no lograron recuperarla. Claude Code reintenta la descarga cuando la conexión se interrumpe, la transferencia se detiene o el archivo descargado no pasa su verificación de checksum, hasta un total de tres intentos. Un error HTTP completo, como un 404, no se reintenta porque el servidor ya respondió. Antes de v2.1.202, una sola conexión interrumpida hacía fallar la descarga de inmediato con el error escueto aborted en lugar de reintentar.

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

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

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

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

Qué hacer:

• Ejecuta claude update nuevamente. En una red que por lo demás funciona bien, la descarga suele completarse en el siguiente intento. Para el mensaje de tiempo agotado, ejecútalo nuevamente desde una red más rápida o menos limitada.
• Si tu red requiere un proxy, establece HTTPS_PROXY antes de ejecutar el instalador o claude update. Consulta Verifica la conectividad de red.
• Si un proxy corporativo sigue cerrando la transferencia, pide a tu equipo de redes que permita la descarga completa desde downloads.claude.ai. Consulta Requisitos de acceso a la red.
• Ejecuta claude doctor desde tu shell para obtener diagnósticos de la instalación

Release verification failed for Claude Code

Este mensaje de claude update o claude install significa que Claude Code no pudo confirmar que la versión que estaba a punto de instalar es auténtica, por lo que no instaló nada. Cualquier versión que ya tengas sigue funcionando.

Release verification failed for Claude Code <version> (<reason>). The update was not installed.

Sigue el paso que corresponda al valor entre paréntesis de tu mensaje:

• Un valor que comienza con sidecar_fetch_: ejecuta el mismo comando nuevamente desde tu shell. claude update tuvo éxito si imprime una línea que comienza con Successfully updated from, y claude install tuvo éxito si imprime Claude Code successfully installed!.
• Cualquier otro valor: intenta el mismo comando nuevamente más tarde

Con cualquier valor, si el mensaje se repite, reporta el problema e incluye el mensaje completo.

Auto-update failed · Run claude doctor en el pie de la sesión

Esta línea roja significa que Claude Code intentó actualizarse en segundo plano y la actualización no se instaló. Puedes seguir trabajando sin hacer nada.

La línea te remite a claude doctor, cuya línea Last update attempt: failed (install_failed) da una fecha pero no una causa. Para terminar la actualización o ver por qué falló, ejecuta claude update en tu shell en su lugar. Si esa instalación también falla, busca el error que imprime claude update en Encuentra tu error.

Comando de instalación incorrecto en Windows

Si ves 'irm' is not recognized, The token '&&' is not a valid statement separator, A parameter cannot be found that matches parameter name 'fsSL' o 'bash' is not recognized as the name of a cmdlet, copiaste el comando de instalación para un shell o sistema operativo diferente. Si el comando imprime el texto del script en lugar de instalar algo, ejecutaste solo una parte del comando.

• irm no reconocido: estás en CMD, no en PowerShell. Tienes dos opciones:

  Abre PowerShell buscando "PowerShell" en el menú Inicio y luego ejecuta el comando de instalación original:

  irm https://claude.ai/install.ps1 | iex
  

  O permanece en CMD y usa el instalador de CMD en su lugar:

  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  

• && no es un separador de instrucciones válido: estás en PowerShell pero ejecutaste el comando del instalador de CMD. Usa el instalador de PowerShell:

  irm https://claude.ai/install.ps1 | iex
  

• A parameter cannot be found that matches parameter name 'fsSL': ejecutaste el instalador de macOS/Linux curl -fsSL ... | bash en Windows PowerShell, donde curl es un alias de Invoke-WebRequest y rechaza los flags -fsSL. Usa el instalador de PowerShell en su lugar:

  irm https://claude.ai/install.ps1 | iex
  

• bash no reconocido: ejecutaste el instalador de macOS/Linux en Windows. Usa el instalador de PowerShell en su lugar:

  irm https://claude.ai/install.ps1 | iex
  

• El comando imprime el texto del script en lugar de instalar: ejecutaste la mitad de descarga del comando sin la parte que lo ejecuta. irm https://claude.ai/install.ps1 por sí solo imprime el script descargado en la terminal. Canalízalo a iex para ejecutarlo:

  irm https://claude.ai/install.ps1 | iex
  

  En CMD, curl -fsSL https://claude.ai/install.cmd sin -o imprime el script por lotes en lugar de guardarlo. Ejecuta el comando completo:

  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  

Sea cual sea el instalador que uses, confirma que funcionó: abre una nueva terminal y ejecuta claude --version, que imprime un número de versión como 2.1.211 (Claude Code).

running scripts is disabled on this system

Instalar o ejecutar Claude Code a través de npm en Windows puede fallar con un SecurityError:

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
...
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException

El mismo error nombra claude.ps1 cuando ejecutas claude después de una instalación con npm. La política de ejecución de PowerShell está bloqueando los scripts lanzadores .ps1 que npm crea para sus comandos. La política se aplica a archivos de script, por lo que no afecta al instalador de PowerShell irm https://claude.ai/install.ps1 | iex, que ejecuta directamente el texto descargado.

Soluciones:

1. Permite los scripts creados localmente para tu usuario y luego intenta nuevamente:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. Llama al lanzador .cmd en su lugar: npm.cmd y claude.cmd hacen el mismo trabajo, y la política no los cubre.
3. Usa el instalador de PowerShell en lugar de npm. Instala un binario en lugar de un script .ps1.

The process cannot access the file durante la instalación en Windows

Si el instalador de PowerShell falla con Failed to download binary: The process cannot access the file ... because it is being used by another process, el instalador no pudo escribir en %USERPROFILE%\.claude\downloads. Esto generalmente significa que un intento de instalación anterior aún se está ejecutando, o que un software antivirus está analizando un binario descargado parcialmente en esa carpeta.

Cierra cualquier otra ventana de PowerShell que esté ejecutando el instalador y espera a que los análisis del antivirus liberen el archivo. Luego elimina la carpeta de descargas y ejecuta el instalador nuevamente:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

claude.exe faltante después de una actualización en Windows

Si tu terminal informa 'claude' is not recognized justo después de que Claude Code se actualizara en Windows, verifica si %USERPROFILE%\.local\bin aún contiene claude.exe. Si ese directorio no está en tu PATH en absoluto, consulta Verifica tu PATH en su lugar. Para actualizarse en Windows, Claude Code cambia el nombre del claude.exe existente para apartarlo como respaldo y mueve la nueva versión a su lugar. Si mover la nueva versión a su lugar falla y Claude Code tampoco puede devolverle el nombre original al respaldo, el directorio conserva el respaldo pero no tiene claude.exe.

El respaldo es un archivo en el mismo directorio cuyo nombre comienza con claude.exe.old. seguido de una marca de tiempo numérica. Ejecuta lo siguiente en PowerShell para devolverle al respaldo más reciente el nombre claude.exe:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

Luego ejecuta claude --version para confirmar la corrección. Un claude.exe restaurado imprime un número de versión.

Si no hay ningún archivo claude.exe.old.*, o claude aún falla después del cambio de nombre, reinstala en su lugar:

irm https://claude.ai/install.ps1 | iex

Antes de v2.1.281, Claude Code podía eliminar el respaldo mientras claude.exe aún faltaba.

La instalación se interrumpe en servidores Linux con poca memoria

Un mensaje Killed durante la instalación generalmente significa que el OOM killer (out-of-memory) de Linux terminó el paso claude install porque el sistema se quedó sin memoria libre. Esto es común en VPS pequeños e instancias en la nube. El script de instalación reporta la causa y termina con el código 137. En este ejemplo, el número de línea y el ID de proceso varían según la versión y la ejecución:

Setting up Claude Code...
bash: line 183: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

La instalación necesita aproximadamente 512 MB de memoria libre, y ejecutar Claude Code necesita más. Consulta los requisitos del sistema.

Soluciones:

1. Agrega espacio de intercambio (swap) si tu servidor tiene RAM limitada. El swap usa espacio en disco como memoria adicional, lo que permite que la instalación se complete incluso con poca RAM física.

   Crea un archivo de swap de 2 GB y habilítalo:

   sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   

   Luego reintenta la instalación:

   curl -fsSL https://claude.ai/install.sh | bash
   

2. Cierra otros procesos para liberar memoria antes de instalar.

3. Usa una instancia más grande si es posible. Claude Code requiere al menos 4 GB de RAM.

Installation was killed before it could finish

El script de instalación informa cuando el paso claude install es terminado por una señal. En Linux, el código de salida 137 significa que el proceso recibió SIGKILL, y en un host con poca memoria eso suele ser el OOM killer (out-of-memory) del kernel. El script imprime esta explicación y termina con el código 137:

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

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

Qué hacer:

• Detén otros procesos para liberar memoria y luego vuelve a ejecutar el instalador
• Agrega espacio de swap o cambia a una instancia más grande. Consulta La instalación se interrumpe en servidores Linux con poca memoria para ver los comandos del archivo de swap.

La instalación se cuelga en Docker

Al instalar Claude Code en un contenedor Docker, instalar como root en / puede causar cuelgues.

Soluciones:

1. Establece un directorio de trabajo antes de ejecutar el instalador. Cuando se ejecuta desde /, el instalador analiza todo el sistema de archivos, lo que causa un uso excesivo de memoria. Establecer WORKDIR limita el análisis a un directorio pequeño:

   WORKDIR /tmp
   RUN curl -fsSL https://claude.ai/install.sh | bash
   

2. Asigna más memoria a Docker si usas Docker Desktop. Los contenedores de compilación comparten la memoria asignada a la máquina virtual de Docker Desktop, así que abre Settings > Resources en Docker Desktop, aumenta el límite de memoria y vuelve a ejecutar la compilación.

Raw mode is not supported durante la instalación

Cuando la configuración administrada por servidor de tu organización incluye cambios que necesitan aprobación de seguridad, las versiones de Claude Code anteriores a 2.1.246 intentan mostrar el diálogo de aprobación durante claude install. El diálogo necesita una terminal en stdin. Cuando el instalador ejecuta claude install desde una tubería, como hace curl -fsSL https://claude.ai/install.sh | bash, stdin es la tubería en lugar de una terminal, por lo que la instalación falla con un error que contiene Raw mode is not supported.

Claude Code v2.1.246 y posteriores no muestran el diálogo durante claude install ni claude update. El comando se ejecuta con la configuración que aprobaste por última vez, y Claude Code muestra el diálogo en tu próxima sesión interactiva. Si la configuración de inicio de tu organización espera la obtención de la configuración, como cuando establece forceRemoteSettingsRefresh, el diálogo aún aparece durante estos comandos, y una instalación ejecutada desde una tubería aún falla.

En todas las demás configuraciones, volver a ejecutar el instalador supera este error, porque el script ejecuta el comando install de la versión más reciente incluso cuando le pides que instale una versión anterior. Vuelve a ejecutar el comando para tu plataforma:

[tab] macOS/Linux

curl -fsSL https://claude.ai/install.sh | bash

[tab] Windows PowerShell

irm https://claude.ai/install.ps1 | iex

claude --version imprime la versión que instaló la nueva ejecución.

claude update o claude doctor se cuelga

claude update y claude doctor analizan tus archivos de configuración del shell en busca de un alias claude obsoleto: ~/.zshrc, ~/.bashrc y ~/.config/fish/config.fish, además, en macOS, el primero que exista de ~/.bash_profile, ~/.bash_login o ~/.profile. Si estableces ZDOTDIR, el archivo de Zsh es $ZDOTDIR/.zshrc en su lugar. Cuando una de esas rutas es un directorio, Claude Code la omite y ambos comandos se completan normalmente. Antes de v2.1.214, un directorio en una de esas rutas hacía que ambos comandos se colgaran y dejaba en blanco la sección System diagnostics de /status. claude doctor se colgaba sin salida; claude update se colgaba justo después de imprimir Checking for updates.

Si encuentras el cuelgue en una versión anterior, localiza el directorio. En la salida de este comando, una línea que comienza con d marca esa ruta como un directorio. Una línea No such file or directory significa que no existe nada en esa ruta y no es la causa:

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

Mueve el directorio a otro lugar, o actualiza a v2.1.214 o posterior. Dado que claude update se cuelga en las versiones afectadas, actualiza volviendo a ejecutar el script de instalación en su lugar.

Claude Desktop sobrescribe el comando claude en Windows

Si instalaste una versión anterior de Claude Desktop, puede registrar un Claude.exe en el directorio WindowsApps que tiene prioridad en el PATH sobre Claude Code CLI. Ejecutar claude abre la aplicación de escritorio en lugar de la CLI.

Actualiza Claude Desktop a la versión más reciente para corregir este problema.

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Git para Windows es opcional. Claude Code usa la herramienta PowerShell cuando Git Bash no está presente, por lo que este error significa que no se encontró ninguno de los dos shells.

Si PowerShell no está en tu PATH, su ubicación predeterminada es C:\Windows\System32\WindowsPowerShell\v1.0\. Agrega ese directorio a tu PATH, o instala PowerShell 7, que proporciona pwsh.

Para instalar Git para Windows en su lugar, descárgalo desde git-scm.com/downloads/win. Durante la instalación, selecciona "Add to PATH." Reinicia tu terminal después de instalar. Instalarlo habilita la herramienta Bash, útil cuando trabajas con scripts y herramientas basadas en Bash.

Si Git ya está instalado pero Claude Code no puede encontrarlo, compara su ubicación con los lugares que Claude Code verifica. Cuando CLAUDE_CODE_GIT_BASH_PATH no está establecido, Claude Code busca bash.exe en este orden:

1. Las ubicaciones de instalación predeterminadas C:\Program Files\Git y C:\Program Files (x86)\Git.
2. El git en tu PATH, usando el bin\bash.exe de esa instalación de Git.

En el paso 2, Claude Code omite un git que se encuentra en la carpeta desde la que iniciaste Claude Code, o debajo de ella en una ruta que contiene node_modules o una carpeta de entorno virtual como .venv o env, por ejemplo C:\dev\env\myproject\Git cuando iniciaste desde C:\dev\env\myproject. Esto evita que Claude Code ejecute un ejecutable que un proyecto colocó allí. Si tu Git está en una ubicación así, apunta CLAUDE_CODE_GIT_BASH_PATH a él.

Para apuntar Claude Code a una instalación específica de Git, encuéntrala ejecutando where.exe git en PowerShell y luego establece la ruta bin\bash.exe de esa instalación como CLAUDE_CODE_GIT_BASH_PATH en tu archivo settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Si CLAUDE_CODE_GIT_BASH_PATH está establecido en la ruta correcta y el archivo existe pero Claude Code aún no lo usa, verifica primero el nombre del archivo. Claude Code acepta solo un archivo llamado bash.exe, sh.exe, bash o sh; con cualquier otro nombre, como el lanzador git-bash.exe de Git para Windows, ignora la variable y detecta automáticamente Git Bash como si no estuviera establecida, registrando una advertencia visible con --debug. Una ruta que no existe recibe el mismo comportamiento de respaldo y la misma advertencia. Antes de v2.1.219, Claude Code usaba cualquier archivo existente como shell sin verificar su nombre, y terminaba al iniciar con Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path cuando la ruta no existía.

Si el nombre del archivo es correcto, puede que esté interfiriendo software de seguridad de endpoints como AppLocker, las directivas de restricción de software de Directiva de grupo o agentes EDR. Pide a tu equipo de TI que agregue claude.exe y los procesos que genera, incluidos cmd.exe y bash.exe, a la lista de permitidos de tu política de protección de endpoints.

Claude Code does not support 32-bit Windows

Windows incluye dos entradas de PowerShell en el menú Inicio: Windows PowerShell y Windows PowerShell (x86). La entrada x86 se ejecuta como un proceso de 32 bits y provoca este error incluso en una máquina de 64 bits. Para verificar en qué caso estás, ejecuta esto en la misma ventana que produjo el error:

[Environment]::Is64BitOperatingSystem

Si esto imprime True, tu sistema operativo está bien. Cierra la ventana, abre Windows PowerShell sin el sufijo x86 y ejecuta el comando de instalación nuevamente.

Si esto imprime False, estás en una edición de Windows de 32 bits. Claude Code requiere un sistema operativo de 64 bits. Consulta los requisitos del sistema.

Discrepancia de binario musl o glibc en Linux

Si ves errores sobre bibliotecas compartidas faltantes como libstdc++.so.6 o libgcc_s.so.1 después de la instalación, es posible que el instalador haya descargado la variante de binario incorrecta para tu sistema.

Error loading shared library libstdc++.so.6: No such file or directory

Esto puede ocurrir en sistemas basados en glibc que tienen instalados paquetes de compilación cruzada de musl, lo que hace que el instalador detecte incorrectamente el sistema como musl.

Soluciones:

1. Verifica qué libc usa tu sistema:

   ldd --version 2>&1 | head -1
   

   Una salida que menciona GNU libc o GLIBC significa glibc. Una salida que menciona musl significa musl.

2. Si estás en glibc pero obtuviste el binario musl, elimina la instalación y reinstala. También puedes descargar manualmente el binario correcto usando el manifiesto en https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json. Abre un issue en GitHub con la salida de ldd --version y ls /lib/libc.musl*.

3. Si realmente estás en musl, como Alpine Linux, instala los paquetes requeridos:

   apk add libgcc libstdc++ ripgrep
   

   En Alpine, ripgrep está en el repositorio community. Si apk reporta que falta el paquete, consulta Configuración de Alpine Linux.

Illegal instruction

Si al ejecutar claude o el instalador se imprime Illegal instruction, el binario nativo usa instrucciones de CPU que tu procesador no admite. Hay dos causas distintas.

Discrepancia de arquitectura. El instalador descargó el binario incorrecto, por ejemplo x86 en un servidor ARM. Verifica con uname -m en macOS o Linux, o $env:PROCESSOR_ARCHITECTURE en PowerShell. Si el resultado no coincide con el binario que recibiste, abre un issue en GitHub con la salida.

Falta el conjunto de instrucciones AVX. Si tu arquitectura es correcta pero aún ves Illegal instruction, probablemente tu CPU carece de AVX u otra instrucción que el binario requiere. Esto afecta aproximadamente a procesadores Intel y AMD anteriores a 2013, y a máquinas virtuales donde el hipervisor no expone AVX al invitado.

En un VPS o VM, ejecuta grep -m1 -ow avx /proc/cpuinfo; un resultado vacío significa que AVX no está disponible para el invitado.

No hay una solución alternativa con el binario nativo; sigue el issue #50384 para conocer el estado, e incluye tu modelo de CPU de grep -m1 "model name" /proc/cpuinfo en Linux o sysctl -n machdep.cpu.brand_string en macOS al reportarlo.

Los métodos de instalación alternativos descargan el mismo binario nativo y no resolverán ninguna de las dos causas.

dyld: cannot load en macOS

Si ves dyld: Symbol not found, dyld: cannot load o Abort trap: 6 durante la instalación, el binario es incompatible con tu versión de macOS o tu hardware.

Un error Symbol not found que hace referencia a libicucore significa que tu versión de macOS es más antigua que la que admite el binario:

dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib

El cargador puede, en cambio, rechazar los comandos de carga del binario, lo que también significa que tu versión de macOS es demasiado antigua:

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

Soluciones:

1. Verifica tu versión de macOS: Claude Code requiere macOS 13.0 o posterior. Abre el menú Apple y selecciona Acerca de esta Mac para verificar tu versión.

2. Actualiza macOS si estás en una versión anterior. El binario usa comandos de carga y bibliotecas del sistema que las versiones anteriores de macOS no admiten. Los métodos de instalación alternativos como Homebrew descargan el mismo binario y no resolverán este error.

Bus error mientras se ejecuta una sesión

Si una sesión en ejecución termina y tu shell imprime Bus error, una causa es que Claude Code ya no pudo leer su propio archivo ejecutable desde el disco. Por ejemplo, el archivo se truncó, o se eliminó en un almacenamiento de red, mientras la sesión se ejecutaba.

Antes del mensaje del shell, el runtime de Claude Code puede imprimir un informe de fallo que incluye panic(main thread): Bus error at address y oh no: Bun has crashed. This indicates a bug in Bun, not your code. Cuando el ejecutable se volvió ilegible, el fallo proviene del archivo ilegible, no de un error en Bun. El informe también puede faltar, si el runtime tampoco pudo leer el código que lo imprime.

Inicia una nueva sesión para continuar. Si Claude Code está instalado en un almacenamiento de red, sigue Instalar en almacenamiento de red para que las actualizaciones no eliminen un binario que las sesiones en ejecución aún necesitan.

Exec format error en WSL1

Si al ejecutar claude en WSL se imprime cannot execute binary file: Exec format error, estás en WSL1 y te afecta una regresión conocida del binario nativo, registrada en el issue #38788. Los encabezados de programa del binario cambiaron de una manera que el cargador de WSL1 no puede manejar.

La solución más limpia es convertir tu distribución a WSL2 desde PowerShell:

wsl --set-version <DistroName> 2

Si necesitas permanecer en WSL1, invoca el binario a través del enlazador dinámico. Agrega esta función a ~/.bashrc dentro de WSL, reemplazando la ruta si tu directorio home es diferente:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

Luego ejecuta source ~/.bashrc y vuelve a intentar claude.

Errores de instalación de npm en WSL

Estos problemas aplican si instalaste Claude Code con npm install -g dentro de WSL. Si usaste el instalador nativo, omite esta sección. En npm 12, instala como se describe en Corregir una instalación con npm 12.

Problemas de detección de SO o plataforma. Si npm reporta una discrepancia de plataforma durante la instalación, probablemente WSL está tomando el npm de Windows. Ejecuta primero npm config set os linux y luego instala con npm install -g @anthropic-ai/claude-code --force. No uses sudo.

exec: node: not found al ejecutar claude. Probablemente tu entorno WSL está usando la instalación de Node.js de Windows. Confírmalo con which npm y which node: las rutas que comienzan con /mnt/c/ son binarios de Windows, mientras que las rutas de Linux comienzan con /usr/. Para corregirlo, instala Node a través del administrador de paquetes de tu distribución de Linux o a través de nvm.

Conflictos de versión de nvm. Si tienes nvm instalado tanto en WSL como en Windows, cambiar de versión de Node en WSL puede fallar porque WSL importa el PATH de Windows de forma predeterminada y el nvm de Windows tiene prioridad. La causa más común es que nvm no está cargado en tu shell. Agrega el cargador de nvm a ~/.bashrc o ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

O cárgalo en tu sesión actual:

source ~/.nvm/nvm.sh

Si nvm está cargado pero las rutas de Windows aún tienen prioridad, antepón explícitamente la ruta de Node de Linux:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

[!WARNING]

Evita deshabilitar la importación del PATH de Windows mediante appendWindowsPath = false, ya que esto impide llamar ejecutables de Windows desde WSL. De manera similar, evita desinstalar Node.js de Windows si lo usas para desarrollo en Windows.

Errores de permisos durante la instalación

Si el instalador nativo falla con errores de permisos, es posible que el directorio de destino no sea escribible. Consulta Verifica los permisos de directorio.

Si instalaste previamente con npm y te encuentras con errores de permisos específicos de npm, cambia al instalador nativo:

curl -fsSL https://claude.ai/install.sh | bash

Binario nativo no encontrado después de la instalación con npm

El paquete npm @anthropic-ai/claude-code descarga el binario nativo como una dependencia opcional por plataforma, como @anthropic-ai/claude-code-darwin-arm64. claude es un script de marcador de posición hasta que se ejecuta el paso postinstall del paquete @anthropic-ai/claude-code y reemplaza el marcador de posición con ese binario. Si se omite la descarga o el paso postinstall, el marcador de posición permanece, y ejecutar claude en macOS y Linux imprime:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

En Windows, bin/claude.exe es ese mismo marcador de posición de script de shell en lugar de un ejecutable real, por lo que PowerShell y CMD reportan que no pueden ejecutar el archivo en lugar de imprimir este mensaje.

Verifica las siguientes causas:

• npm 12 omite el paso postinstall de forma predeterminada. Cuando instalas o actualizas Claude Code con npm 12, npm igualmente termina la instalación sin ejecutar el paso. Consulta Corregir una instalación con npm 12.
• Las dependencias opcionales están deshabilitadas. Elimina --omit=optional de tu comando de instalación de npm, --no-optional de pnpm o --ignore-optional de yarn, y verifica que .npmrc no establezca optional=false. Luego reinstala. El binario nativo se entrega solo como dependencia opcional, por lo que no hay alternativa en JavaScript si se omite, y volver a ejecutar install.cjs no puede colocar un binario que nunca se descargó.
• Los scripts de instalación están deshabilitados. --ignore-scripts y algunas configuraciones de pnpm omiten el paso postinstall pero aún descargan el paquete de plataforma. Ejecuta node node_modules/@anthropic-ai/claude-code/install.cjs como sugiere el mensaje, o reinstala sin el flag. Si postinstall no puede ejecutarse en absoluto en tu entorno, node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs encuentra el paquete descargado y lo inicia, a costa de un proceso de Node adicional en cada inicio. Si el wrapper imprime Could not find native binary package en su lugar, el paquete de plataforma nunca se descargó, así que primero corrige la causa de dependencias opcionales descrita arriba.
• Plataforma no admitida. Se publican binarios precompilados para darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 y win32-arm64. Claude Code no distribuye un binario para otras plataformas; consulta los requisitos del sistema. En FreeBSD, el instalador reporta la plataforma como no admitida. Antes de v2.1.205, trataba FreeBSD como Linux y descargaba un binario que no podía ejecutarse.
• Al mirror corporativo de npm le faltan los paquetes de plataforma. Asegúrate de que tu registro replique los ocho paquetes de plataforma @anthropic-ai/claude-code-* además del metapaquete.

Corregir una instalación con npm 12

Si claude imprime Error: claude native binary not installed. después de una instalación o actualización con npm, o en Windows el shell no puede ejecutarlo, ejecuta npm --version. Una versión que comienza con 12 significa que, a menos que tu configuración de npm lo permita, npm omitió el paso postinstall de Claude Code, que es el que coloca el binario en su lugar. Para cualquier otra versión, verifica las otras causas.

Para corregir una instalación con npm 12, cambia al instalador nativo o permite el paso:

• Cambia al instalador nativo: instala con el instalador nativo y luego desinstala el paquete de npm. Así las actualizaciones ya no usan npm, por lo que el error no vuelve.

• Quédate en npm: para una instalación global con npm, agrega Claude Code a allow-scripts en tu configuración de usuario de npm. Así npm ejecuta los scripts de instalación de Claude Code en cada instalación y actualización posterior, y en las instalaciones de proyecto cuyo package.json no establece allowScripts.

  Usa el instalador nativo para una instalación local en ~/.claude/local. Úsalo también si los scripts de tu package.json llaman a npm install y los ejecutas con pnpm 9, pnpm 10, Yarn 1 u otra herramienta que les pase este ajuste. En npm 12.1 y posteriores, esas instalaciones pueden fallar con EALLOWSCRIPTS una vez guardado el ajuste.

  1. Si npm --version imprimió 12.0.x, actualiza npm a 12.1 o posterior, por ejemplo con npm install -g npm@latest. En 12.0.x, las instalaciones de proyecto que inicia una herramienta npx o un script npm run pueden fallar con EALLOWSCRIPTS una vez guardado el ajuste.

  2. Ejecuta npm config get allow-scripts y anota los paquetes que liste, porque el siguiente comando reemplaza el valor completo. Guarda el ajuste con esos paquetes dentro de las comillas, como en "allow-scripts=@anthropic-ai/claude-code,<package>":

     npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user
     

  3. Reinstala:

     npm install -g @anthropic-ai/claude-code
     

     Si este comando o el paso 1 fallan con EACCES, cambia al instalador nativo en lugar de volver a ejecutarlo con sudo. Claude Code ejecuta npm sin sudo cuando se actualiza a sí mismo, por lo que las actualizaciones automáticas fallarían de la misma manera.

  4. Si claude --version no imprime un número de versión, verifica las otras causas.

  Para deshacerlo, establece la lista de nuevo sin @anthropic-ai/claude-code, o elimina la lista completa con npm config delete allow-scripts --location=user. En npm 12, el error vuelve después de tu próxima actualización.

Error ENOTEMPTY de npm durante una actualización o reinstalación

Cuando ejecutas npm install -g @anthropic-ai/claude-code sobre una instalación existente, npm puede fallar al mover a un lado el directorio del paquete antiguo:

npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/.claude-code-tVWAnUUt
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename '...'

La línea npm error path nombra el directorio que npm no pudo mover. Elimina ese directorio y cualquier directorio .claude-code-* sobrante junto a él, que ejecuciones interrumpidas anteriores pueden dejar. Los comandos a continuación encuentran tu directorio global de paquetes con npm root -g; si el directorio que nombra la línea npm error path no está dentro del directorio que imprime npm root -g, por ejemplo porque cambiaste de versión de Node con nvm, elimina en su lugar los directorios que nombra el error:

[tab] macOS/Linux

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"

Luego elimina cualquier directorio temporal sobrante. Si Zsh imprime no matches found, no había ninguno que eliminar:

rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*

[tab] Windows PowerShell

Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

Luego reinstala. En npm 12, sigue Corregir una instalación con npm 12. De lo contrario, ejecuta:

npm install -g @anthropic-ai/claude-code

Confirma con claude --version, que imprime un número de versión como 2.1.211 (Claude Code).

Inicio de sesión y autenticación

Estas secciones abordan fallos de inicio de sesión, errores de OAuth y problemas con tokens.

Restablece tu inicio de sesión

Cuando el inicio de sesión falla y la causa no está clara, una reautenticación limpia resuelve la mayoría de los casos:

1. Ejecuta /logout para cerrar sesión por completo
2. Cierra Claude Code
3. Reinicia con claude y completa el proceso de autenticación de nuevo

Si el navegador no se abre automáticamente durante el inicio de sesión, presiona c para copiar la URL de OAuth a tu portapapeles y luego pégala manualmente en un navegador. Esto también funciona cuando la URL se divide en varias líneas en una terminal estrecha o SSH y no se puede hacer clic en ella directamente.

OAuth error: Invalid code

Si ves OAuth error: Invalid code. Please make sure the full code was copied, el código de inicio de sesión expiró o se truncó al copiar y pegar.

Soluciones:

• Presiona Enter para reintentar y completa el inicio de sesión rápidamente después de que se abra el navegador
• Escribe c para copiar la URL completa si el navegador no se abre automáticamente
• Si usas una sesión remota/SSH, el navegador puede abrirse en la máquina equivocada. Copia la URL que se muestra en la terminal y ábrela en tu navegador local.

403 Forbidden después de iniciar sesión

Si ves API Error: 403 Request not allowed después de iniciar sesión:

• Usuarios de Claude Pro/Max/Ultra: verifica que tu suscripción esté activa en claude.ai/settings
• Usuarios de Anthropic Console: confirma que tu cuenta tenga el rol "Claude Code" o "Developer". Los administradores lo asignan en la página Members de la Console en platform.claude.com/settings/members.
• Detrás de un proxy: los proxies corporativos pueden interferir con las solicitudes a la API. Consulta configuración de red para configurar el proxy.

Claude Code access has not been granted for this account

Si la página de inicio de sesión muestra Authorization failed con el mensaje Claude Code access has not been granted for this account. Contact your administrator. después de iniciar sesión desde Claude Code, tu organización de Claude Enterprise estableció tu rol como Custom y ninguno de los roles personalizados asignados a tus grupos otorga acceso a Claude Code. Con el rol Custom, obtienes acceso solo a través de esos roles personalizados, así que nada que cambies en Claude Code resuelve este error.

Para obtener acceso:

1. Pide a un Owner de tu organización de Claude que asigne a uno de tus grupos un rol personalizado que otorgue acceso a Claude Code, o que cambie tu rol de Custom a un rol estándar como User. Los Owners administran los roles en la configuración de roles de la organización.
2. Después de que el Owner haga el cambio, ejecuta claude e inicia sesión de nuevo.

Esta organización ha sido deshabilitada con una suscripción activa

Si ves API Error: 400 ... "This organization has been disabled" a pesar de tener una suscripción activa de Claude, una variable de entorno ANTHROPIC_API_KEY está anulando tu suscripción. Esto ocurre comúnmente cuando una clave de API antigua de un empleador o proyecto anterior sigue configurada en el perfil de tu shell.

Cuando ANTHROPIC_API_KEY está presente y la has aprobado, Claude Code usa esa clave en lugar de las credenciales OAuth de tu suscripción. En modo no interactivo con el flag -p, la clave siempre se usa cuando está presente. Consulta precedencia de autenticación para ver el orden de resolución completo.

Para usar tu suscripción en su lugar, elimina la variable de entorno y quítala del perfil de tu shell:

[tab] macOS/Linux

unset ANTHROPIC_API_KEY
claude

[tab] Windows PowerShell

Remove-Item Env:ANTHROPIC_API_KEY
claude

Revisa ~/.zshrc, ~/.bashrc o ~/.profile en busca de líneas export ANTHROPIC_API_KEY=... y elimínalas para que el cambio sea permanente. En Windows, revisa tu perfil de PowerShell en $PROFILE y tus variables de entorno de usuario en busca de ANTHROPIC_API_KEY. Ejecuta /status dentro de Claude Code para confirmar qué método de autenticación está activo.

El inicio de sesión OAuth falla en WSL2, SSH o contenedores

Si no se abre ningún navegador, o si el navegador inicia tu sesión y luego muestra un error de conexión para una dirección localhost, puedes terminar de iniciar sesión sin resolver ninguno de los dos problemas. En su lugar, inicia sesión a través de la URL de inicio de sesión independiente que la terminal muestra encima de su solicitud para pegar:

1. Copia la URL de inicio de sesión

En la solicitud interactiva de inicio de sesión, presiona c para copiar la URL, o selecciónala en la terminal. Con claude auth login, copia la URL que imprime.

2. Inicia sesión a través de esa URL

Abre la URL en un navegador de tu máquina local e inicia sesión. El navegador muestra entonces un código en lugar de volver a localhost.

3. Pega el código

Pega ese código en la terminal, en la solicitud que comienza con Paste code here.

Si pegar el código en la solicitud interactiva no hace nada, probablemente el atajo de pegado de tu terminal no está llegando al campo de entrada. Prueba el atajo de pegado alternativo de tu terminal, a menudo clic derecho o Shift+Insert en Windows Terminal, o usa claude auth login en su lugar, que lee el código pegado desde la entrada estándar:

claude auth login

Esta alternativa también aplica en Windows nativo o en cualquier terminal donde falle pegar en la solicitud interactiva.

En WSL2, si no se abrió ningún navegador, también puedes hacer que Claude Code abra tu navegador de Windows la próxima vez configurando la variable de entorno BROWSER con la ruta de ese navegador:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

Sesión no iniciada o token expirado

Si Claude Code te pide iniciar sesión de nuevo después de una sesión, es posible que tu token de OAuth haya expirado.

Ejecuta /login para volver a autenticarte. Si esto ocurre con frecuencia, verifica que el reloj de tu sistema sea preciso, ya que la validación de tokens depende de marcas de tiempo correctas.

Las sesiones paralelas en una misma máquina comparten un inicio de sesión guardado y coordinan su renovación para que solo un proceso actualice el token a la vez. Para saber qué hacen las demás sesiones después de que vuelves a iniciar sesión en una de ellas, consulta Not logged in.

Antes de la v2.1.211, reactivar la máquina desde la suspensión podía hacer que dos sesiones renovaran con el mismo token, lo que revocaba el inicio de sesión guardado y pedía a todas las sesiones abiertas que iniciaran sesión de nuevo a la vez.

En macOS, Claude Code guarda las credenciales en el Keychain de inicio de sesión. Cuando el Keychain rechaza la escritura, por ejemplo cuando está bloqueado en una sesión SSH o su contraseña no está sincronizada con la contraseña de tu cuenta, Claude Code guarda tu inicio de sesión en el archivo de texto plano ~/.claude/.credentials.json en su lugar. Un inicio de sesión de Console que crea una clave de API falla hasta que el Keychain vuelva a admitir escritura.

Para que el Keychain vuelva a admitir escritura y trasladar tu inicio de sesión de nuevo al Keychain cifrado:

1. Verifica el acceso al Keychain

Ejecuta claude doctor para verificar el acceso al Keychain. Cuando el Keychain rechaza escrituras, el informe muestra una advertencia que comienza con macOS Keychain is not writable, seguida de una solución sugerida. Cuando el informe no muestra ninguna advertencia del Keychain, el Keychain admite escritura y puedes pasar al último paso.

2. Desbloquea el Keychain

security unlock-keychain ~/Library/Keychains/login.keychain-db

Ingresa la contraseña de tu Keychain cuando el comando la solicite y luego ejecuta claude doctor de nuevo. Si el desbloqueo funcionó, el informe ya no muestra la advertencia del Keychain.

3. Vuelve a sincronizar la contraseña del Keychain si el desbloqueo no ayuda

Abre Acceso a Llaveros (Keychain Access), selecciona el llavero login y elige Edit > Change Password for Keychain "login" para sincronizarlo con la contraseña de tu cuenta. Luego ejecuta claude doctor de nuevo. Pasa al siguiente paso una vez que el informe ya no muestre la advertencia del Keychain.

4. Cierra sesión y vuelve a iniciarla

Una vez que el Keychain vuelva a admitir escritura, Claude Code traslada las credenciales de vuelta la próxima vez que escriba una credencial. Para forzarlo ahora, ejecuta /logout y luego /login. Cerrar sesión elimina todas las credenciales almacenadas, incluido el contenido del archivo de texto plano, los inicios de sesión guardados de servidores MCP y los valores sensibles de plugins, así que prepárate para volver a autorizar los servidores MCP y volver a ingresar los secretos de los plugins después. Al iniciar sesión de nuevo, tu inicio de sesión se almacena en el Keychain.

El inicio de sesión falla en un directorio home de red

Cuando una solicitud falla con API Error: 401 y tu directorio de configuración está en un sistema de archivos de red, verifica si ese sistema de archivos o tu cuota en él está lleno. Sin espacio disponible, Claude Code no puede guardar un inicio de sesión nuevo o renovado en el archivo .credentials.json de texto plano, y claude auth login aún puede imprimir Login successful.

1. Libera espacio en el sistema de archivos

Elimina los archivos que ya no necesites en el sistema de archivos que contiene ~/.claude, o el directorio que configuraste en CLAUDE_CONFIG_DIR.

2. Inicia sesión de nuevo

Ejecuta /login en el prompt de Claude Code o claude auth login en tu shell.

Antes de la v2.1.318, cuando Claude Code guardaba el archivo de inicio de sesión en un sistema de archivos de red lleno, podía reemplazar un inicio de sesión almacenado aún válido por un archivo vacío. Los comandos posteriores informaban entonces Not logged in.

Las credenciales de Bedrock, Agent Platform o Foundry no se cargan

Si configuraste Claude Code para usar un proveedor de nube y ves Could not load credentials from any providers en Amazon Bedrock, Could not load the default credentials en Agent Platform de Google Cloud, o ChainedTokenCredential authentication failed en Microsoft Foundry, probablemente la CLI de tu proveedor de nube no esté autenticada en el shell actual.

Para Amazon Bedrock, confirma que tus credenciales de AWS sean válidas:

aws sts get-caller-identity

Para Agent Platform de Google Cloud, confirma que ANTHROPIC_VERTEX_PROJECT_ID y CLOUD_ML_REGION estén configuradas en tu shell y luego configura las credenciales predeterminadas de la aplicación:

gcloud auth application-default login

Para Microsoft Foundry, confirma que ANTHROPIC_FOUNDRY_API_KEY esté configurada, o inicia sesión con la CLI de Azure para que la cadena de credenciales predeterminada pueda encontrar tu cuenta:

az login

Si las credenciales funcionan en tu terminal pero no en la extensión de VS Code o JetBrains, probablemente el proceso del IDE no heredó el entorno de tu shell. Configura las variables de entorno del proveedor en la configuración propia del IDE, o inicia el IDE desde una terminal donde ya estén exportadas.

Consulta Amazon Bedrock, Agent Platform de Google Cloud o Microsoft Foundry para la configuración completa del proveedor.

Aún atrapado

Si ninguno de los anteriores resuelve su problema:

1. Verifique el repositorio de GitHub para problemas conocidos, o abra uno nuevo con su sistema operativo, el comando de instalación que ejecutó, y la salida de error completa
2. Si claude --version funciona pero algo más está mal, ejecute claude doctor para un informe de diagnóstico automatizado
3. Si puede iniciar una sesión, use /feedback dentro de Claude Code para reportar el problema
4. Si el problema es con su cuenta en lugar de la instalación, como un bucle de inicio de sesión, una suscripción que no se reconoce, u una organización deshabilitada, contacte al soporte de Anthropic: inicie sesión en claude.ai (Usuarios de Console: platform.claude.com), haga clic en sus iniciales en la esquina inferior izquierda, y seleccione Obtener ayuda. Consulte Cómo obtener soporte para el flujo completo.