Solucionar problemas de plugins

Esta página enumera mensajes de error y síntomas para plugins de Claude Code y para mercados, los catálogos desde los que Claude Code instala plugins. Cada entrada proporciona la causa, una solución y lo que ve una vez que la solución funciona. Cuando un mensaje nombra un plugin o mercado, la entrada muestra un marcador de posición como <name> en su lugar. Utilice esta página si instala plugins, los crea, aloja un mercado o administra plugins para una organización.

Estos casos se tratan en otras páginas:

Por qué los alcances, la caché y la precedencia se comportan de la manera en que lo hacen: lee la referencia de carga de plugins
Buscar un flag, campo o comando: usa la referencia de comandos de plugins, la referencia del manifiesto o la referencia de marketplaces
Un mensaje hooks module not loaded o hooks module did not load: el plugin es un mod, así que lee El mod no se carga

Busque el mensaje exacto que vio. Cada mensaje se enumera bajo la etapa que lo produce, que no siempre es el comando que ejecutó. Por ejemplo, una instalación puede fallar porque falta un mercado, por lo que ese mensaje está bajo Add a marketplace.

Find where `/plugin` runs

/plugin es un comando que escribe dentro de una sesión de terminal de Claude Code en ejecución, y abre un panel interactivo. Las entradas en esta sección cubren los lugares donde puede escribirlo pero no puede ejecutarse, y los comandos que no existen.

`/plugin isn't available in this environment`

Escribió /plugin en algún lugar que no sea una sesión de terminal de Claude Code, y Claude respondió con esta línea en lugar de abrir nada. Recibe esta respuesta en una sesión que no tiene terminal para dibujar el panel /plugin en: non-interactive mode con claude -p, el Agent SDK, la pestaña Code de la aplicación de escritorio Claude, el panel de extensión de VS Code, y el navegador en claude.ai/code. En el panel de extensión de VS Code, solo una línea /plugin con algo después, como /plugin install <plugin>@<marketplace>, recibe esta respuesta. /plugin o /plugins escrito solo abre el diálogo Manage plugins. Instale el plugin desde la superficie en la que se encuentra:

Aplicación de escritorio Claude, sesión local o SSH: haga clic en el botón + junto al prompt, luego Plugins, luego Add plugin para abrir el plugin browser
Extensión de VS Code: use la pestaña VS Code bajo Install a plugin
Claude Code en la web, o una sesión de escritorio en la nube: una sesión en la nube no tiene navegador de plugins. Vea la pestaña Cloud session bajo Install a plugin para lo que carga una sesión en la nube
Una terminal a la que tiene acceso: ejecute claude y escriba /plugin allí, o ejecute claude plugin install <plugin>@<marketplace> en su shell sin iniciar una sesión

Cuando una instalación de terminal funciona, /plugin imprime un resumen de instalación que comienza con ✓ Installed <plugin>. y claude plugin install imprime Successfully installed plugin: <plugin>@<marketplace>.

`zsh: no such file or directory: /plugin`

Escribió /plugin ... en un prompt de shell, y el shell informó que no existe ningún archivo llamado /plugin. Bash informa bash: /plugin: No such file or directory. /plugin es un comando que escribe dentro de una sesión de Claude Code, no en el prompt de shell. Inicie una sesión y escriba el mismo comando allí:

claude

Luego, en el prompt de Claude Code:

/plugin install <plugin>@<marketplace>

Una instalación exitosa imprime un resumen que comienza con ✓ Installed <plugin>. Si la instalación en sí falla, su mensaje está bajo Add a marketplace o Install a plugin. Para instalar desde el shell sin iniciar una sesión, ejecute claude plugin install <plugin>@<marketplace> en su lugar.

`The term '/plugin' is not recognized as the name of a cmdlet`

Escribió /plugin ... en un prompt de PowerShell, y /plugin es un comando de Claude Code, no un programa. Bash y Zsh informan su propia forma de este error. Use cualquiera de estos en su lugar:

Ejecute claude, luego escriba /plugin en el prompt de Claude Code
Ejecute claude plugin install <plugin>@<marketplace> en PowerShell sin iniciar una sesión

`claude: command not found` after `claude plugin ...`

Ejecutó claude plugin install ... en su shell, y el shell no pudo encontrar claude en absoluto. En Windows el mensaje es 'claude' is not recognized as the name of a cmdlet o 'claude' is not recognized as an internal or external command. La causa no es el comando del plugin. Sigue Verifica tu PATH y luego reintenta el comando del plugin.

`Unknown command` and command spellings that don’t exist

Escribió un comando de plugin que vio en algún lugar y obtuvo Unknown command: /<name> en una sesión, o error: unknown command '<name>' o error: unknown option '<flag>' del binario claude en su shell. Circulan varias formas de escribir comandos que Claude Code no tiene. La tabla siguiente asigna cada una al comando real. La referencia de comandos de plugins enumera los subcomandos y sus flags.

Escribió	Lo que Claude Code dice	Use en su lugar
`claude plugin add <source>`	`error: unknown command 'add'`	`claude plugin marketplace add <source>` para agregar un mercado, o `claude plugin install <plugin>@<marketplace>` para instalar un plugin
`claude plugin install <plugin> --project`	`error: unknown option '--project'`	`claude plugin install <plugin>@<marketplace> --scope project`
`/install <plugin>`	`Unknown command: /install`	`/plugin install <plugin>@<marketplace>`
`/plugin add <source>`	El panel `/plugin` se abre en la pestaña Discover	`/plugin marketplace add <source>`
`marketplace.anthropic.com` como fuente	`Invalid marketplace source format. Try: owner/repo, https://..., or ./path`	`anthropics/claude-plugins-official` para el mercado oficial

Estos comandos se ven mal pero funcionan:

claude plugins es un alias de claude plugin
claude plugin remove es un alias de claude plugin uninstall
/plugins y /marketplace en una sesión abren el mismo panel que /plugin

Add a marketplace

Un mercado es un catálogo que agrega a Claude Code desde un repositorio git, una URL o una ruta local. Estas entradas cubren los mensajes que obtiene cuando agregar uno falla o una actualización posterior falla.

`Marketplace "claude-plugins-official" not found`

Ejecutó /plugin install <plugin>@claude-plugins-official en una sesión, y Claude Code informó que no tiene ningún mercado con ese nombre. El mercado oficial aún no está registrado en esta máquina. Claude Code normalmente lo registra por su cuenta la primera vez que inicia una sesión de terminal interactiva. No se ha ejecutado si solo ha usado Claude Code a través de la extensión de VS Code, y omite o difiere ese paso:

Cuando una política bloquea la fuente
Cuando se establece CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL
Después de un intento fallido que está esperando para reintentar

Los comandos de shell claude plugin nunca lo registran por usted. Agréguelo, luego reintente la instalación:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code imprime Successfully added marketplace: claude-plugins-official, y /plugin marketplace list muestra el mercado con su fuente. Para cualquier otro nombre de mercado en este mensaje, vea Marketplace "<name>" not found. La misma cadena también aparece en la pestaña /plugin Errors, la lista de fallos de carga del panel, cuando un plugin listado en su configuración nombra un mercado que no ha agregado.

`Marketplace "<name>" not found`

Ejecutó /plugin install en una sesión y Claude Code informó que no tiene ningún mercado con ese nombre. Dos formas del comando llegan a este mensaje:

/plugin install <plugin>@<name>: la línea de instalación, a menudo una que alguien le envió, nombra un mercado que no ha agregado. El resto de esta entrada cubre encontrarlo y agregarlo.
/plugin install <source> con una ruta, URL, u owner/repo: esta forma informa el mensaje en lugar de instalar, incluso para una fuente que ya ha agregado. Para instalar desde una fuente en un comando, vea Agregar un mercado e instalar en un comando.

Si el nombre comienza con claudeai-, el mercado se aloja en claude.ai, y lo agrega por nombre desde su shell con claude plugin marketplace add --claudeai <name>. Vea Add a marketplace from claude.ai. Para cualquier otro nombre, una línea de instalación nombra un mercado pero no dice dónde se aloja el mercado, y Claude Code no tiene un índice para buscar un nombre de mercado. Pida a quien le envió la línea la fuente del mercado, que es un owner/repo de GitHub, una URL de git, o una ruta. Luego agregue el mercado y ejecute la línea de instalación nuevamente. Un mercado que alguien le envía es de terceros, así que revise el plugin antes de instalarlo. Si ya agregó el mercado, verifique la ortografía contra /plugin marketplace list.

`Invalid marketplace source format`

Ejecutaste /plugin marketplace add <source>, claude plugin marketplace add <source> o claude plugin install <plugin> --marketplace <source>, y Claude Code respondió Invalid marketplace source format. Try: owner/repo, https://..., or ./path. Claude Code acepta una fuente en una de estas formas:

Un atajo de owner/repo de GitHub
Una URL https:// o http://
Una URL SSH user@host:path
Una ruta local que comienza con ./, ../, /, o ~

Un nombre simple como claude-plugins-official no coincide con ninguno de ellos. Tampoco un nombre de host simple como marketplace.anthropic.com. Vuelva a escribir la fuente en una de las formas aceptadas:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code imprime Successfully added marketplace: <name> cuando la adición funciona.

`'<source>' is not a valid GitHub owner/repo shorthand`

Pasó una fuente con una barra que no es owner/repo, como github.com/owner/repo o una ruta gitlab.example.com/group/project. Claude Code la rechazó con este mensaje y una lista de formas aceptadas. El atajo owner/repo es solo de GitHub y tiene que seguir las reglas de nomenclatura de GitHub, por lo que un nombre de host o un segmento de ruta adicional falla. Pase la fuente en la forma que coincida con dónde se aloja el mercado:

Un repositorio en cualquier host: la URL de clonación completa
Un marketplace.json alojado: su URL https://
Un checkout local: ./path o una ruta absoluta

Por ejemplo, para agregar el mercado oficial por su URL de clonación, en una sesión:

/plugin marketplace add https://github.com/anthropics/claude-plugins-official.git

Una adición exitosa imprime Successfully added marketplace: <name>.

`Invalid git URL`

Agregó un mercado, instaló un plugin, o ejecutó una actualización desde una dirección git, y el comando falló con Invalid git URL en su mensaje. Claude Code verifica cada dirección git antes de ejecutar git. Rechaza una dirección cuyo protocolo no admite. También rechaza una dirección que git podría leer como nombrando un servidor o carpeta diferente del que muestra la dirección. El texto después de la dirección nombra qué cambiar. Reescriba la dirección como dice el mensaje y ejecute el comando nuevamente. Un rechazo que en su lugar dice is blocked by enterprise policy proviene de la configuración de su organización. Vea Marketplace source is blocked by enterprise policy.

`Path does not exist: <path>`

Pasó una ruta local a marketplace add, y nada existe en esa ruta. Una ruta relativa se resuelve contra su directorio actual. Verifique la ruta resuelta en el mensaje. Luego ejecute el comando desde el directorio desde el que comienza la ruta relativa, o pase una ruta absoluta al directorio del mercado. Una adición exitosa imprime Successfully added marketplace: <name>. Claude Code acepta un directorio que contiene .claude-plugin/marketplace.json, o una ruta a un archivo .json. Una ruta a cualquier otro archivo falla con File path must point to a .json file (marketplace.json).

`Marketplace file not found at <path>/.claude-plugin/marketplace.json`

Claude Code clonó o descargó el mercado pero no encontró marketplace.json en la ruta esperada dentro de él. El comando de adición lo informa como Failed to add marketplace: Marketplace file not found at .... La ubicación predeterminada es .claude-plugin/marketplace.json en la raíz del repositorio, y la marketplace reference enumera las ubicaciones aceptadas. La solución difiere para el propietario y para todos los demás:

Usted es el propietario del mercado: coloque el archivo en esa ubicación y vuelva a agregar el mercado
Alguien más lo aloja: pida al propietario la fuente exacta que publican

`Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name`

Agregaste un marketplace, y el name en su marketplace.json no es válido como la parte posterior a @ en un id de plugin como my-plugin@my-marketplace. Claude Code rechaza la adición y no registra nada. El resto del mensaje indica la regla para el nombre. En este ejemplo, _internal incumple la regla porque comienza con _:

Cannot add marketplace "_internal": Claude Code cannot install plugins from a marketplace with this name. Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.

Dale al marketplace un nombre que cumpla esa regla y luego vuelve a agregarlo:

Eres el propietario del marketplace: cambia name en marketplace.json, por ejemplo a internal-tools
Otra persona lo aloja: pídele al propietario que cambie el nombre

Antes de v2.1.295, Claude Code informaba la adición de este ejemplo como exitosa.

`Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it`

Agregaste un marketplace, y el name en su marketplace.json es uno de los nombres de miembro que tiene todo objeto de JavaScript, como constructor, toString o valueOf. Claude Code reserva esos nombres, por lo que rechaza la adición y no registra nada. Nombres reservados los enumera. En este ejemplo, el marketplace se llama constructor:

Cannot add marketplace "constructor": Claude Code reserves this name and cannot register a marketplace under it. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.

Si un archivo de configuración declara el marketplace en extraKnownMarketplaces, el intento de Claude Code de agregarlo al iniciar falla de la misma manera, y el mensaje aparece en la pestaña Errors de /plugin. Dale al marketplace otro nombre y luego vuelve a agregarlo:

Eres el propietario del marketplace: cambia name en marketplace.json
Otra persona lo aloja: pídele al propietario que cambie el nombre

Antes de v2.1.296, agregar un marketplace así fallaba con un error interno en lugar de este mensaje.

`SSH authentication failed` or `HTTPS authentication failed`

Agregó o actualizó un mercado desde un repositorio git, y el clonado falló con Failed to clone marketplace repository: seguido de una de estas líneas. Primero verifique el repositorio en sí: un owner/repo mal escrito, un repositorio que no existe, o un repositorio privado que no puede ver también termina en este mensaje. Abra la URL del repositorio en su navegador, o ejecute git ls-remote <url> en su terminal, para confirmar que existe y tiene acceso. Si el repositorio es correcto, la causa son las credenciales. Claude Code ejecuta git con prompts interactivos deshabilitados, por lo que no puede pedirle una contraseña, una frase de contraseña de clave, o una credencial de la manera que lo haría su terminal. Si git necesita solicitar, ve fatal: Cannot prompt because user interactivity has been disabled o terminal prompts disabled en el error original. Solo las credenciales que ya funcionan de forma no interactiva tienen éxito:

SSH: ssh -T git@<host> debe tener éxito sin solicitar una frase de contraseña, y el host ya debe estar en known_hosts
HTTPS: su asistente de credenciales debe contener un token para el host. Para GitHub, ejecute gh auth login y gh auth setup-git. Para otro host, almacene un token de acceso personal en su asistente de credenciales de git. Pruebe con git ls-remote <url>

Una vez que git ls-remote tiene éxito en su terminal sin un prompt, ejecute la adición o actualización nuevamente. Una adición exitosa imprime Successfully added marketplace: <name>. Una actualización exitosa imprime Successfully updated marketplace: <name> desde su shell, o ✔ Updated 1 marketplace en una sesión. Para hacer que Claude Code omita SSH para fuentes owner/repo de GitHub, establezca CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1. Sin él, Claude Code clona esas fuentes sobre SSH cuando una clave SSH para github.com parece estar configurada, y vuelve a HTTPS cuando el clonado SSH falla. Para lo que las actualizaciones automáticas en segundo plano pueden y no pueden hacer con sus credenciales, vea What background auto-update does with credentials.

`SSH host key is not in your known_hosts file`

Agregó un mercado sobre SSH desde un host al que nunca se ha conectado, y el clonado falló con esta línea y una sugerencia ssh -T git@<host>. Para un host cuya clave cambió, el mensaje es SSH host key has changed con una sugerencia ssh-keygen -R <host> en su lugar. Claude Code clona con StrictHostKeyChecking=yes, por lo que rechaza un host cuya clave no ha aceptado aún en lugar de aceptar la clave automáticamente. Conéctese una vez desde su terminal para aceptar la huella digital, luego reintente:

ssh -T git@github.com

Para un repositorio público, agregue el mercado por su URL https:// en su lugar para evitar SSH completamente.

`Command 'git' not found or is in an unsafe location`

En Windows, agregó un mercado y Claude Code informó Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location (current directory). Claude Code busca git en su PATH y rechaza ejecutar uno encontrado solo en el directorio actual. Para solucionarlo, instale Git e intente nuevamente:

Install Git for Windows

Instale Git para Windows para que git esté en su PATH.

Open a new terminal

Abra una nueva terminal para que se aplique el PATH actualizado.

Confirm git runs

Confirme que git --version imprime una versión.

Retry the add

Ejecute el comando marketplace add nuevamente.

`Git clone timed out after 120s`

Agregó o actualizó un mercado, y falló con Git clone timed out after 120s, seguido de una sugerencia para establecer CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. Clonar un mercado, y re-clonar uno para actualizarlo, obtiene 120 segundos por defecto. Para un repositorio grande o una conexión lenta, aumente el límite. El valor está en milisegundos:

Bash or Zsh
PowerShell

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

$env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

Luego reintente en el mismo shell. Si el repositorio es un monorepo, limite el checkout a los directorios que nombra con claude plugin marketplace add <source> --sparse <paths>.

Marketplace updates keep failing offline

Trabaja en un entorno donde el host git del mercado es inaccesible, y cada sesión repite una actualización fallida en segundo plano. Su checkout existente del mercado permanece en su lugar y el inicio no se retrasa. Cada sesión, para un mercado con auto-update on, Claude Code verifica el host git del mercado para nuevos commits en segundo plano. Cuando esa verificación no puede alcanzar el host, intenta clonar el mercado nuevamente, y sin conexión ese clonado también falla. Establezca esta variable para omitir el intento de re-clonación y mantener el uso del checkout existente cuando la verificación no puede alcanzar el host:

Bash or Zsh
PowerShell

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

$env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"

Con la variable establecida, Claude Code omite la re-clonación solo para un checkout que ya contiene .claude-plugin/marketplace.json. Un mercado que nunca fue clonado o cuyo clonado se detuvo a mitad de camino aún obtiene el intento de clonación, así que agréguelo una vez mientras está en línea. Para una implementación completamente sin conexión, pre-rellene el directorio de plugins en el tiempo de compilación de imagen con CLAUDE_CODE_PLUGIN_SEED_DIR en su lugar, siguiendo Seed containers and CI.

Marketplace add fails on a GitHub Enterprise Server host

Agregó un mercado desde una URL de GitHub Enterprise Server (GHES) y obtuvo un error de política, o lo agregó desde claude.ai y obtuvo un error de acceso a GitHub. Ambos casos están en la página de GHES:

Un error de política significa que su organización restringió las fuentes del mercado y un administrador necesita agregar un hostPattern para el host
Un error de acceso a GitHub en claude.ai significa que su propia cuenta de GitHub Enterprise aún no está conectada

Instalar un plugin

Agregaste un marketplace y ejecutaste una instalación, y la instalación se detuvo con un mensaje en lugar de instalar algo. Estas entradas cubren esos mensajes. También cubren los mensajes relacionados que aparecen más tarde en la pestaña Errors de /plugin, o como una pestaña Discover vacía, cuando no se puede encontrar, leer o confiar en un plugin o en su marketplace.

`Plugin "<name>" not found in marketplace "<marketplace>"`

Ejecutaste /plugin install <name>@<marketplace> o claude plugin install <name>@<marketplace>, y el nombre del plugin no está en la copia del catálogo de ese marketplace que hay en tu máquina. claude plugin install en tu shell imprime el mismo mensaje cuando no has agregado el marketplace en absoluto. Si claude plugin marketplace update <marketplace> responde entonces Marketplace '<marketplace>' not found, primero agrega el marketplace.

`not found in marketplace` con una sugerencia de actualización

La sugerencia dice Your local copy may be out of date — try claude plugin marketplace update <marketplace> o The marketplace couldn't be refreshed (...). Claude Code no actualizó el marketplace antes de la búsqueda, por ejemplo cuando estás sin conexión, así que tu copia del catálogo puede estar desactualizada. Actualízalo con el nombre del marketplace y luego vuelve a instalar:

/plugin marketplace update <marketplace>

claude plugin marketplace update imprime Successfully updated marketplace: <name>, y /plugin marketplace update muestra ✔ Updated 1 marketplace. Si la instalación reintentada imprime el mismo mensaje, revisa el nombre como se describe en not found in marketplace sin sugerencia. Cuándo Claude Code actualiza un marketplace antes de una instalación enumera los otros casos en los que la actualización no se ejecuta.

`not found in marketplace` sin sugerencia

Lo más probable es que el problema sea el nombre. Abre /plugin, ve a Discover y copia el nombre de la lista. Antes de v2.1.232, Claude Code actualizaba el marketplace indicado solo después de que la búsqueda fallara, y solo cuando tenía la actualización automática activada.

`Plugin "<name>" not found in any marketplace`

Ejecutaste /plugin install <name> sin @marketplace, y ningún marketplace registrado tiene ese plugin. claude plugin install <name> informa Plugin "<name>" not found in any configured marketplace. Sin un nombre de marketplace, claude plugin install busca en los catálogos que ya tiene y no los actualiza antes, y /plugin install actualiza solo los marketplaces que tienen la actualización automática activada. Indica el marketplace y Claude Code lo actualizará antes de buscar el plugin:

/plugin install <name>@<marketplace>

Cuando la instalación funciona, ves ✓ Installed <plugin>. en una sesión, o Successfully installed plugin: <plugin>@<marketplace> desde claude plugin install. Si no sabes qué marketplace incluye el plugin, ejecuta /plugin marketplace list para ver los marketplaces que tienes, y busca el nombre del plugin en Discover dentro de /plugin.

`Plugin '<name>@<marketplace>' is already installed globally`

Ejecutaste /plugin install para un plugin que ya está instalado en el alcance de usuario o mediante la configuración administrada, y Claude Code lo rechazó con Use '/plugin' to manage existing plugins. Si escribiste el nombre del plugin sin @<marketplace>, el mensaje omite globally. El plugin ya está disponible en todos los proyectos, así que no hay nada que agregar. Para cambiar su alcance, habilitarlo o deshabilitarlo, o configurarlo, abre /plugin y ve a Installed. Un plugin instalado solo en el alcance de proyecto o local no activa este mensaje. Claude Code te permite instalarlo también en el alcance de usuario, para que esté disponible en otros proyectos. claude plugin install en tu shell imprime un mensaje diferente. Para un plugin ya instalado en el alcance de destino, imprime Plugin "<name>@<marketplace>" is already installed (scope: user) y sale con 0. Si falta su directorio de caché, el mismo comando lo vuelve a descargar. Instalaste un plugin mediante claude plugin install, /plugin o una sugerencia de instalación en una sesión, y Claude Code lo rechazó con esta línea, o con would share its saved data with. El id del plugin rechazado y el id de un plugin instalado corresponden a la misma carpeta en el disco: son iguales una vez que . y @ se escriben como -. En macOS y Windows, los ids que difieren solo en mayúsculas también corresponden a la misma carpeta. Instalar ambos pondría los archivos de un plugin en la carpeta del otro, así que Claude Code lo rechaza y el plugin instalado conserva sus archivos. El mensaje indica la salida:

El otro plugin está instalado: el mensaje dice Only one of the two can be installed. e indica el comando claude plugin uninstall, o el paso de desinstalación en /plugin, que elimina el otro plugin. Ejecútalo y luego vuelve a instalar. Para saber qué elimina la desinstalación, consulta Qué elimina y qué conserva una desinstalación.
Ambos ids llegan en una sola instalación, como un plugin y una dependencia que necesita: ningún orden de instalación ayuda. Solo un mantenedor del marketplace que incluye los dos plugins puede arreglarlo, cambiando el nombre de uno de ellos. Cuando los dos provienen de marketplaces diferentes, puede hacerlo un mantenedor de cualquiera de ellos.

`This plugin uses a source type your Claude Code version does not support`

Instalaste un plugin cuya entrada en el marketplace usa un tipo de fuente que esta versión de Claude Code no puede obtener, y Claude Code se detuvo con este mensaje y Update Claude Code and try again. Actualiza Claude Code y luego reintenta la instalación. Los tipos de fuente están en la referencia de marketplaces.

`Plugin archive integrity check failed`

Instalaste un plugin que se distribuye como archivo zip, y Claude Code lo rechazó con esta línea y The archive was not installed. La entrada del plugin en el marketplace usa una fuente archive con un sha256 fijado, y el hash del archivo descargado no coincide con el valor fijado. El mensaje completo se ve así:

Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

La solución es distinta para quien publica y para quien instala:

Publicas el plugin: vuelve a calcular el hash del archivo exacto que sirve la URL y actualiza el sha256 en la entrada del marketplace. Usa shasum -a 256 my-plugin.zip, o Get-FileHash -Algorithm SHA256 my-plugin.zip en PowerShell
Instalas el plugin: ejecuta /plugin marketplace update <name> en una sesión para actualizar el catálogo por si la entrada se corrigió, y luego reintenta la instalación. Si los hashes siguen sin coincidir después de la actualización, pregúntale al propietario del marketplace qué archivo fijó antes de instalar

`An npm plugin source must name a registry package`

Un plugin cuya entrada en el marketplace usa una fuente npm no se pudo instalar, actualizar o cargar, y el mensaje incluye esta oración. Claude Code revisó el valor package de la entrada antes de obtener nada y lo rechazó. El mensaje indica el valor y el motivo:

"github:acme/formatter" was not installed: it is not an http or https link. An npm plugin source must name a registry package (name or name@version) or link to a tarball file. For a plugin in a git repository, use a "github", "url" or "git-subdir" source.

El propietario del marketplace tiene que cambiar la entrada:

Si eres tú: cambia package a un valor que acepte la referencia de la fuente de plugins npm, o cambia la entrada a una fuente github, url o git-subdir
Si no eres tú: informa el mensaje al propietario del marketplace

`Marketplace "<name>" is registered from an untrusted source`

Un marketplace que agregaste antes dejó de cargarse, y también sus plugins. Esta línea aparece en la pestaña Errors de /plugin o en la siguiente actualización. El marketplace está registrado con un nombre reservado para los marketplaces oficiales de Anthropic, pero su fuente registrada no es un repositorio de GitHub de anthropics. Los nombres reservados se vuelven a comprobar cada vez que un marketplace se carga o se actualiza, por lo que el marketplace y los plugins instalados desde él dejan de cargarse. El mensaje completo indica el nombre reservado y la solución:

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

La solución es distinta para usuarios y para quienes publican:

Usas el marketplace: en tu shell, ejecuta claude plugin marketplace remove <name> y luego vuelve a agregar el marketplace desde el repositorio oficial de github.com/anthropics
Publicas un marketplace de terceros que usaba el nombre antes de que se reservara: cámbiale el nombre y pide a los usuarios que lo vuelvan a agregar desde tu fuente

Antes de v2.1.205, Claude Code comprobaba el nombre solo cuando agregabas el marketplace, así que una entrada registrada antes de que su nombre se reservara seguía cargándose.

`Marketplace "<name>" is added but ignored`

El marketplace tiene una entrada en ~/.claude/plugins/known_marketplaces.json, pero la entrada no pasó una comprobación que Claude Code ejecuta cada vez que lee ese archivo, por lo que el marketplace y los plugins instalados desde él dejan de cargarse. En tu shell, claude plugin list informa cada plugin afectado con una línea que indica el motivo y la solución:

Marketplace team-tools is added but ignored. Its location is on a network drive, has "." or ".." in its path, or couldn't be checked. Re-add the marketplace (one added from a folder or file must be re-added from a copy on this computer), or, to trust a folder on a network drive, declare it under extraKnownMarketplaces in user or managed settings.

En una sesión, la pestaña Errors de /plugin pone el nombre del marketplace entre comillas, termina la línea después del motivo y muestra la solución en la línea de abajo. La oración que sigue a is added but ignored indica la comprobación que la entrada no pasó:

Its location is on a network drive, has "." or ".." in its path, or couldn't be checked, o la misma oración sobre The folder or file it was added from: el directorio del marketplace, o la ruta local desde la que se agregó, está en una ubicación de red, tiene un segmento . o .. en su ruta, o no se pudo comprobar
Its git URL can't be used: <reason> o Its URL can't be read as an https:// or http:// address: la URL de origen registrada en la entrada es una desde la que Claude Code se niega a clonar u obtener
Its source doesn't match its extraKnownMarketplaces entry in user or managed settings: la entrada no coincide con la declaración de extraKnownMarketplaces del mismo nombre

Cuando (see the debug log) sigue a is added but ignored en lugar de un motivo, Claude Code rechaza el nombre del marketplace, por ejemplo otra grafía de un nombre reservado. El registro de depuración indica la entrada. Qué hacer:

Sigue la solución del mensaje. En tu shell, ejecuta claude plugin marketplace remove <name>, luego vuelve a agregar el marketplace desde una fuente compatible o una ruta local y reinstala sus plugins, que el comando de eliminación desinstala. El comando de eliminación funciona con una entrada ignorada
Para mantener un marketplace en una ubicación de red, decláralo en extraKnownMarketplaces en tu configuración de usuario o en la configuración administrada; una declaración en el .claude/settings.json o .claude/settings.local.json de un repositorio no cuenta
Para una fuente que difiere de su declaración en la configuración, vuelve a agregar el marketplace desde la fuente declarada o cambia la declaración. claude plugin marketplace add rechaza la misma discrepancia; consulta la entrada correspondiente de Cannot add marketplace
Para un nombre rechazado, elimina el marketplace usando el comando que aparece después de Remove it: cuando la línea lo incluye; volver a agregarlo con el mismo nombre se rechaza de nuevo

Antes de v2.1.286, fuera cual fuera el motivo, claude plugin list informaba un marketplace así como Marketplace <name> not found, y la pestaña Errors de /plugin lo informaba como Marketplace "<name>" is registered but was refused (see the debug log). El motivo solo aparecía en el registro de depuración. En v2.1.286, las oraciones del motivo y de la solución usaban otra redacción, como Its recorded location is network-shaped or unclassifiable (never probed).

`Plugin <name> has a corrupt manifest file` o `has an invalid manifest file`

Claude Code obtuvo el plugin y luego no pudo leer su .claude-plugin/plugin.json. En el shell, el <name> de esta línea puede ser un nombre de directorio temporal; el prefijo Failed to install plugin "<name>@<marketplace>" lleva el nombre real del plugin. La redacción indica qué comprobación falló:

corrupt manifest file, seguido de JSON parse error:: el archivo no es JSON válido
invalid manifest file, seguido de Validation errors:: el archivo se analiza pero no cumple el esquema, por ejemplo name: Invalid input cuando falta un campo obligatorio

claude plugin install informa cualquiera de los dos como Failed to install plugin "<name>@<marketplace>": y sale con código 1. El autor del plugin tiene que corregir el archivo, y el plugin no se puede instalar hasta entonces:

Si eres tú: ejecuta claude plugin validate <plugin-directory> en tu shell para ver el mismo error con la ruta problemática y luego corrige el archivo
Si no eres tú: informa el mensaje al propietario del marketplace

`Plugin directory not found at path: <path>`

La pestaña Errors de /plugin muestra esto para un plugin habilitado que su marketplace incluye mediante una ruta relativa, como ./plugins/my-plugin, cuando no existe ningún directorio en esa ruta dentro del marketplace. Si mantienes el marketplace, corrige la ruta source de la entrada o restaura la carpeta. De lo contrario, informa el mensaje al propietario del marketplace. Marketplace directory not found at path: <path> significa, en cambio, que falta el directorio del propio marketplace. En un marketplace que agregaste desde una ruta local, ese directorio se movió o se eliminó. Restáuralo, o elimina el marketplace y vuelve a agregarlo desde su nueva ubicación.

`No plugins available` o `No marketplaces configured`

Abriste /plugin y la pestaña Discover está vacía, o claude plugin marketplace list imprimió No marketplaces configured. No hay ningún marketplace registrado, así que no hay catálogo que mostrar. En una sesión, agrega el marketplace oficial, anthropics/claude-plugins-official:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code imprime Successfully added marketplace: claude-plugins-official, y Discover muestra sus plugins. La página de marketplaces de Anthropic enumera los otros marketplaces que puedes agregar.

`Marketplace "<name>" is already added from a different source`

Indicaste una nueva fuente 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 esa fuente tiene el mismo nombre que un marketplace que ya agregaste desde una fuente diferente. Claude Code conserva el marketplace existente en lugar de reemplazarlo, y el plugin no se instala. El mensaje completo se ve así:

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

Elige qué fuente quieres:

El marketplace que ya agregaste: instala desde él por nombre con /plugin install <plugin>@<name>
La nueva fuente: ejecuta /plugin marketplace remove <name> y luego reintenta la instalación

`Cannot add marketplace "<name>": its source doesn't match its extraKnownMarketplaces entry in user or managed settings`

Agregaste un marketplace, y el name de su marketplace.json ya tiene una entrada de extraKnownMarketplaces en tu configuración de usuario o en la configuración administrada. La fuente que indicaste difiere de la que incluye esa entrada, así que Claude Code rechaza la adición y no registra nada. Dos fuentes coinciden cuando tienen el mismo tipo y el mismo valor en cada campo. Una entrada que establece un ref que no pasaste cuenta como diferente. Una entrada github también cuenta como diferente cuando indicaste el repositorio como una URL https://github.com/, porque Claude Code registra esa URL como una fuente git. Haz una de estas cosas:

Usar la fuente declarada: Claude Code registra por sí solo los marketplaces declarados en la configuración, así que primero ejecuta /plugin marketplace list en una sesión. Si la lista muestra el nombre, el marketplace ya está registrado y no hay nada que agregar. Si la lista no lo muestra, agrégalo con la fuente escrita tal como la escribe la entrada. Para una entrada cuyo objeto source es { "source": "github", "repo": "acme-corp/claude-plugins", "ref": "v1.2.0" }, ejecuta esto:
/plugin marketplace add acme-corp/claude-plugins#v1.2.0
Usar la nueva fuente: edita o elimina la entrada de extraKnownMarketplaces y luego vuelve a agregar el marketplace. Si la declara la configuración administrada, pídeselo a tu administrador

Antes de v2.1.287, el mensaje decía

Cannot add marketplace "<name>": its network source differs from the one declared for it in settings (kind, target, or a fetch-shaping field such as headers / ref / path / sparsePaths)

. Seleccionaste plugins para instalar en el menú de /plugin, ninguno se instaló y el menú se cerró con este resumen de lo que falló. Algunos motivos, como la salida de git tras una clonación fallida, muestran solo su primera línea. Cuando un motivo así se acortó, el resumen termina con Installing a plugin from its details (Enter) in /plugin shows its full error. Qué hacer depende de si el resumen acortó el motivo:

Corrige lo que indica el motivo entre paréntesis
Cuando el motivo se acortó, ejecuta /plugin, selecciona el plugin en la pestaña Discover y presiona Enter para instalarlo desde sus detalles. Si la instalación falla ahí, la vista de detalles muestra el error completo

`Could not move the new copy of this plugin version into <path>`

Cuando instalas un plugin, Claude Code descarga una copia nueva de sus archivos y la mueve a la carpeta de esa versión en la caché de plugins. Este mensaje significa que el movimiento falló, normalmente porque otro programa estaba usando la carpeta mientras se ejecutaba la instalación. El código del sistema de archivos aparece entre paréntesis:

Could not move the new copy of this plugin version into /home/user/.claude/plugins/cache/acme-tools/formatter/1.2.0: the new copy or the version folder stayed busy while the install ran (ENOTEMPTY) — usually a scanner still reading the freshly downloaded files, another program using that folder, or another process re-creating it. The previously installed copy was moved back. Run the install again once other Claude Code sessions or programs using that folder have finished.

El mensaje indica qué pasó con la copia que estaba instalada antes, lo que te dice si el plugin sigue funcionando:

The previously installed copy was moved back: la versión que tenías sigue instalada
had to be removed first, was not moved back o could not be moved back: esa versión del plugin no está instalada hasta que una instalación tenga éxito
Ninguna oración de ese tipo: no había una copia anterior, así que la versión todavía no está instalada

En Windows, cuando otro programa retiene la propia copia instalada, el mensaje dice en cambio que esa copia could not be replaced y que It was not replaced and the new copy was discarded, así que la versión que tenías sigue instalada. Una lista Left on disk indica carpetas apartadas dentro de la caché. Una instalación posterior de esa versión o una limpieza de la caché de plugins las elimina, así que no necesitas borrarlas. Para corregir la instalación:

Cierra otras sesiones de Claude Code, editores y terminales que estén usando la carpeta del plugin en ~/.claude/plugins/cache y luego vuelve a ejecutar la instalación
Cuando el mensaje indique revisar los permisos de la carpeta de la caché de plugins, restaura tu permiso de escritura en la carpeta que indica y libera espacio en disco, y luego vuelve a ejecutar la instalación

Errores de dependencias

Un plugin que declara dependencias puede no instalarse, o instalarse y quedar deshabilitado, cuando una dependencia no se puede satisfacer. El mensaje te llega en el momento de la instalación o en el momento de la carga:

Durante la instalación: el rechazo se devuelve como el mensaje de error de la instalación
Cuando el plugin se carga: el problema aparece en claude plugin list y en la pestaña Errors de /plugin, y Claude Code mantiene deshabilitado el plugin afectado hasta que lo resuelvas

La tabla enumera cada mensaje y su solución. Para declarar dependencias como autor, consulta Dependencias de plugins.

Mensaje	Significado	Cómo resolverlo
`Dependency "<dep>" is not installed`	Una dependencia declarada no está instalada.	Instálala en tu shell con `claude plugin install <dep>@<marketplace>`, o desinstala el plugin. Si el marketplace de la dependencia aún no está registrado, agrégalo y ejecuta `/reload-plugins` en tu sesión, lo que instala las dependencias faltantes que puede resolver.
`"<name>@synced" is loaded from your claude.ai account but meets a marketplace dependency only for other claude.ai plugins`, dentro del mensaje `is not installed`	La dependencia indica un marketplace, y un plugin con ese nombre se carga desde tu cuenta de claude.ai. El plugin que declara la dependencia no se carga desde claude.ai, así que el plugin de claude.ai no la satisface.	En tu shell, ejecuta `claude plugin install <dep>@<marketplace>` para instalar la dependencia desde su marketplace. Entonces se carga la copia del marketplace en lugar de la de claude.ai.
`Dependency "<dep>" is disabled`	La dependencia está instalada pero desactivada.	Habilita la dependencia, o desinstala el plugin que la necesita.
`Requires "<dep>" <range>, installed <version>`	La versión de la dependencia instalada está fuera del rango declarado por el plugin.	Actualiza la dependencia a una versión dentro del rango, o desinstala el plugin.
`<Plugin or Dependency> "<name>" has conflicting version requirements`	Ninguna versión satisface todos los rangos que la fijan. El mensaje enumera los rangos.	Desinstala o actualiza uno de los plugins en conflicto, o pide al autor original que amplíe su restricción.
`... has version requirements too complex to intersect` o `has an invalid version requirement`	Un rango no es semver válido, o los rangos combinados no se pueden intersecar.	Corrige el rango no válido o simplifica las cadenas `\|\|` largas.
`... has no git tag satisfying <range>`	El repositorio de la dependencia no tiene ninguna etiqueta `<name>--v*` dentro del rango.	Comprueba que el proyecto original etiquete sus versiones con esa convención, o flexibiliza el rango.
`Dependency "<dep>" (required by <plugin>) is in <marketplace>, which is not in the allowlist`	La dependencia está en un marketplace diferente, y la resolución entre marketplaces está desactivada de forma predeterminada.	Instala tú mismo la dependencia en el mismo alcance, en tu shell con `claude plugin install <dep>@<marketplace>` más el `--scope` en el que estás instalando el plugin, y luego reintenta.

Para verlos de forma programática, ejecuta claude plugin list --json en tu shell. Los plugins con problemas incluyen un campo errors con los mensajes y un campo errorDetails con un type para cada uno: las tres primeras filas son dependency-unsatisfied y la cuarta es dependency-version-unsatisfied.

Plugin installed but not working

La instalación tuvo éxito, pero las skills, hooks, o servidores del plugin no están haciendo nada. Comience con Plugin doesn’t appear or its skills don’t show up, que le dice dónde Claude Code informa lo que cargó, luego coincida con el mensaje.

Plugin doesn’t appear or its skills don’t show up

Instaló un plugin y escribió / esperando sus skills, o le pidió a Claude que lo use, y nada sucedió. Verifique el estado del plugin antes de cambiar nada:

Confirm the plugin is installed and enabled

Ejecute /plugin y abra Installed. Confirme que el plugin está listado y habilitado. claude plugin list en su shell imprime la misma lista con la versión, scope, y Status: ✔ enabled de cada plugin.

Read the Errors tab

Abra la pestaña Errors en el mismo panel. Cada entrada empareja un mensaje con una línea de orientación. La mayoría de los mensajes en el resto de esta sección provienen de esa pestaña.

Reload if you installed during this session

Si el plugin está instalado y sin errores pero lo instaló durante esta sesión, ejecute /reload-plugins. Imprime Reloaded: con conteos de plugins, skills, agents, hooks, y servidores. Cuando algo falló agrega N errors during load. Run /plugin for details.

Si el plugin se carga sin error y sus skills aún no aparecen, el siguiente paso difiere para su propio plugin y para el de alguien más:

Un plugin que está construyendo: vea Plugin loads but its skills are missing
Un plugin que alguien más publicó: abra Installed en /plugin y abra el panel de detalles del plugin, que enumera lo que contiene el plugin. Un plugin que no enumera skills allí no tiene ninguno para ofrecer cuando escribe /

`Run /reload-plugins to apply.`

El resumen de instalación en /plugin terminó con Run /reload-plugins to apply. en lugar de Plugin is now active. Al mismo tiempo, puede aparecer un aviso Plugins changed. Run /reload-plugins to activate. encima del prompt. Claude Code no activó el plugin durante la instalación, ya sea porque activarlo invalidaría la caché de prompt o porque el intento de activación falló. No necesita escribir el comando. El panel se cierra y Claude Code ejecuta /reload-plugins para usted, o lo pone en cola hasta que termine la respuesta que se está transmitiendo. Lea lo que esa recarga imprime:

Reloaded: con conteos de plugins, skills, agents, hooks, y servidores: el plugin ahora está activo. Cuando algo falló al cargar, la línea agrega N errors during load. Run /plugin for details.
This reload changes MCP tools (...) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.: la recarga agregaría o eliminaría un servidor MCP de plugin, o la herramienta LSP, e invalidaría su caché de prompt. Para el caso de LSP la línea comienza This reload adds the LSP tool o This reload removes the LSP tool. Ejecutelo con --force para activar el plugin de todas formas, o inicie una nueva sesión

Antes de v2.1.268, una instalación que no se activó durante la instalación permaneció pendiente hasta que ejecutó /reload-plugins usted mismo. Antes de v2.1.246, el conteo de skills en ese resumen incluía solo las entradas commands/ de un plugin, por lo que una recarga podría cargar las skills SKILL.md de un plugin e informar 0 skills.

`The packages it lists are not installed` o `were not installed, because ...`

/plugin y claude plugin list muestran una de estas notas en un plugin cuya instalación de dependencias no dejó ningún directorio node_modules. El plugin se carga, pero las partes que necesitan los paquetes faltantes podrían no funcionar.

are not installed: la instalación puede ejecutarse para este plugin pero no terminó, por ejemplo porque falló o se agotó el tiempo de espera. Para reintentar la instalación, ejecuta en tu shell el comando claude plugin update que indica la nota, o actualiza el plugin desde /plugin
claude plugin update formatter@my-marketplace
Si el reintento falla, la salida indica la causa. Mientras CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC esté establecida, claude plugin update y /plugin omiten el reintento e informan que el plugin está en su versión más reciente.
were not installed, because ...: la instalación no puede ejecutarse para este plugin, y la nota indica el motivo, como un lockfile de Yarn, pnpm o bun.lockb, o un lockfile cuyo gestor de paquetes no está instalado en esta computadora. Actualizar el plugin no instala los paquetes mientras ese motivo persista. Si el motivo es el lockfile, el autor del plugin tiene que reemplazarlo. Si falta un gestor de paquetes, instálalo y luego actualiza el plugin

`Plugin "<name>" not cached at <path>`

La pestaña Errors muestra esta línea con la orientación Run /plugin to refresh the plugin cache. Claude Code tiene un registro de instalación para el plugin, pero el directorio al que apunta el registro falta, por ejemplo después de que limpió la caché. Reinstale el plugin desde su shell. claude plugin install <name>@<marketplace> descarga nuevamente un plugin cuyo directorio de instalación falta aunque su registro exista:

claude plugin install <name>@<marketplace>

Luego ejecute /reload-plugins en su sesión. La entrada de la pestaña Errors desaparece y el plugin está de vuelta bajo Installed.

`installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`

El mensaje aparece en estas formas:

claude plugin list: lo imprime como una Note:
claude plugin install, uninstall, y update: se niegan con Plugin "<name>" was not installed:, Plugin "<name>" was not uninstalled:, o Plugin "<name>" was not updated:, seguido del mismo texto
--json en cualquiera de esos tres comandos: la línea de resultado lleva el mismo message y failureCode: "install_records_unreadable"
Varios registros de este tipo: el mensaje lee holds records under
El archivo completo declara un formato que esta versión no conoce: el mensaje lee installed_plugins.json is in a format (version <N>) that this version of Claude Code does not know en su lugar

El registro nombrado en installed_plugins.json es JSON válido bajo un id de plugin válido, pero sus campos no se analizan para esta versión. Lo más probable es que otra versión de Claude Code lo escribió, quizás una más nueva. Mientras el registro esté allí, esta versión no reescribe el archivo, por lo que el registro no se pierde. Tome las opciones del mensaje en orden:

Actualice Claude Code con claude update.
Si no puede actualizar, desinstale el plugin nombrado con la versión de Claude Code que escribió el registro.
Si ninguno ayuda, elimine el registro de installed_plugins.json a mano, luego reinicie Claude Code o ejecute /reload-plugins.

`installed_plugins.json could not be read and was rebuilt`

claude plugin list imprime esta nota, con la ruta de un archivo guardado nombrado installed_plugins.unreadable.<date>.<hash>.kept, mientras ese archivo se encuentre junto a installed_plugins.json. Un installed_plugins.json que no es JSON válido, o no es una lista de plugins, no puede decir qué instaló. Abra el archivo .kept para ver qué registró el archivo antiguo, e reinstale los plugins que le faltan. Claude Code nunca vuelve a leer el archivo, y el archivo envejece en el cronograma cleanupPeriodDays.

`install records under names that no version of Claude Code can use were removed from installed_plugins.json`

claude plugin list imprime esta nota, con la ruta de una copia nombrada installed_plugins.set-aside.<date>.<hash>.json, mientras esa copia se encuentre junto a installed_plugins.json. La nota termina Nothing needs doing about these copies. Un registro en installed_plugins.json se encontraba bajo una clave que no es un id de plugin válido, por lo que ninguna versión de Claude Code puede usarlo. El resto del archivo se carga normalmente. Claude Code copia los registros inutilizables en el archivo .set-aside y los elimina de la lista. Claude Code nunca vuelve a leer las copias, y las copias envejecen en el cronograma cleanupPeriodDays.

`does not load (...), so Claude Code ignores the whole file`

El comando funcionó. El archivo de configuración que nombra la advertencia tiene un error, por lo que Claude Code ignora el archivo completo, incluido todo lo que el comando escribió allí, hasta que lo corrijas. Corrige el error que nombra la advertencia. Para un valor que Claude Code no acepta, Corregir un archivo de configuración dañado explica cómo hacerlo. Luego vuelve a ejecutar el comando si su cambio ya no está en el archivo. La advertencia aparece después de la línea de éxito de claude plugin install, enable, disable o claude plugin marketplace add en tu shell:

⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.

El texto entre paréntesis nombra el error:

its "<key>" is not valid: el ajuste entre comillas contiene un valor que Claude Code no acepta. Busca el ajuste en la referencia de configuración para ver los valores que admite. Cuando falla más de un valor, el texto nombra el primer ajuste y cuenta los demás, como en its "permissions" and 1 other value are not valid.
it is not a JSON object: el nivel superior del archivo no es un objeto JSON, como un archivo cuyo nivel superior es un arreglo.

`Disabled in ~/.claude/settings.json but still loads`

Estableció un plugin en false en ~/.claude/settings.json, y su fila en claude plugin list o /plugin muestra este mensaje seguido de la fuente que lo habilita, como — project settings enable it, which overrides your user setting. Un true en esa fuente de mayor precedencia está anulando su configuración de usuario. Para optar por no participar en un plugin habilitado por proyecto en su máquina, establezca el id en false en .claude/settings.local.json, que tiene mayor precedencia que el archivo del proyecto. Para las otras fuentes que el mensaje puede nombrar, vea Disabled in user settings but still loads. Si claude plugin list en su lugar marca el plugin required by your org, ningún archivo de configuración está involucrado: su organización marca ese plugin sincronizado como requerido en claude.ai, y se carga incluso si lo deshabilitó anteriormente. Vea Plugins synced from claude.ai.

`Plugin "<name>" is enabled in project settings but isn't installed here`

La pestaña Errors muestra esta línea para un plugin que el .claude/settings.json de su proyecto habilita, con la orientación Run claude plugin install <name>@<marketplace> --scope project to install it for this project. La configuración de un repositorio puede habilitar un plugin para todos los que lo abren, pero no lo instala. Cuando el plugin proviene de una fuente externa como un repositorio de GitHub o un paquete npm, Claude Code no lo descarga hasta que lo instale usted mismo. Ejecute el comando de la línea de orientación en su shell, luego recargue:

claude plugin install <name>@<marketplace> --scope project

Después de ejecutar /reload-plugins en su sesión, la entrada de la pestaña Errors se ha ido y el plugin está listado bajo Installed. Si su organización pre-instala plugins para usted, lo hace a través de configuración administrada en su lugar. Vea Pre-install and require plugins.

Un plugin sigue instalado después de `plugin uninstall` en Windows

En Windows, ejecutas claude plugin uninstall con alcance de proyecto o local e informa que tuvo éxito, pero claude plugin list o /plugin siguen mostrando el plugin. installed_plugins.json tenía dos registros de instalación del plugin para la carpeta del proyecto, cada uno con la ruta de la carpeta escrita de forma distinta, y una desinstalación elimina solo uno de ellos. Para comprobarlo, ejecuta claude plugin list --json en tu shell. La fila restante del plugin tiene un projectPath que escribe la carpeta de forma distinta a donde ejecutaste la desinstalación, como c:\work\app en lugar de C:\work\app. Vuelve a ejecutar el mismo comando de desinstalación, con el mismo --scope, desde la misma carpeta. La segunda ejecución no encuentra ningún registro con su propia forma de escribir la ruta, así que elimina el que tiene la otra forma. Para una instalación con alcance de proyecto:

claude plugin uninstall <name>@<marketplace> --scope project

Luego vuelve a ejecutar claude plugin list --json para confirmar que la fila desapareció. Antes de v2.1.295, la segunda ejecución falla con Plugin "<name>" is not installed in project scope. Ejecuta claude update y luego vuelve a ejecutar la desinstalación.

`Failed to load hooks from <path>` and hooks that don’t fire

Los hooks de un plugin no se ejecutan, o uno bloquea una acción. O la pestaña Errors muestra un fallo de carga para ellos, los hooks se cargan y ve avisos <Event> hook error o un error de bloqueo en la transcripción, o un hook se carga sin error y nunca se dispara.

Hooks fail to load

La pestaña Errors muestra uno de estos mensajes:

Failed to load hooks from <path>: <reason>: hooks/hooks.json no es JSON válido o falla el esquema de hooks. La razón nombra el error de análisis o validación. Corrija el archivo. Para detectar un problema de sintaxis JSON en hooks/hooks.json antes de publicar el plugin, ejecute claude plugin validate <plugin-directory> en su shell
hooks path not found: <path>: el campo hooks del manifiesto nombra un archivo que no existe en esa ruta relativa a la raíz del plugin. Corrija la ruta o agregue el archivo

`hook error` notices in the transcript

Un aviso de la forma ... hook error: Failed with non-blocking status code: <stderr> significa que el hook se ejecutó y su comando falló. Por ejemplo, Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found significa que el shell que Claude Code generó no pudo encontrar node. Instálelo, o asegúrese de que esté en el PATH del terminal desde el que inicia claude. Si el stderr muestra la ruta del plugin cortada en un espacio, el comando en forma de shell del hook usa ${CLAUDE_PLUGIN_ROOT} fuera de comillas y la ruta de instalación contiene un espacio. Envuelva la variable entre comillas dobles o use exec form. Para encontrar la variable sin comillas, ejecute claude plugin validate en el directorio del plugin y busque su advertencia de entrecomillado. Si el aviso dice Failed to run: Plugin directory does not exist: <path>, consulta Plugin directory does not exist. Para cualquier otro error, ejecute el comando del hook usted mismo desde el directorio del plugin para ver la salida completa, o capture el stderr completo con debug logging.

A plugin hook blocks a tool call or prompt

Un hook que sale con código 2 bloquea la acción para la que se ejecutó. Cuando un hook de plugin bloquea de esta manera y su stderr es el mensaje de bloqueo, el error termina con This hook comes from the <plugin> plugin. para que sepa qué plugin deshabilitar o corregir. Antes de v2.1.281, el error no nombraba el plugin. Si ese mensaje muestra la ruta del plugin cortada en un espacio, aplique la solución de ${CLAUDE_PLUGIN_ROOT} sin comillas.

Hook loads but never fires

Si un hook se carga sin errores pero nunca se dispara, primero ejecuta /plugin en tu sesión y abre los detalles del plugin. Una nota allí que comienza con Its hooks.json hooks do not run significa que otro plugin habilitado con el mismo nombre registró sus hooks en su lugar, y Hooks cuando dos plugins habilitados comparten nombre indica cuál es esa copia y cómo cambiarla. De lo contrario, revisa la definición del hook y luego obsérvalo ejecutarse:

Check the event name

Los nombres de eventos distinguen mayúsculas de minúsculas, así que confirme que el suyo coincida exactamente, por ejemplo PostToolUse.

Check the matcher

Confirme que el matcher del hook coincida con el nombre de la herramienta.

Trigger the event on purpose

Para un hook PostToolUse, pida a Claude que edite un archivo.

Read the debug log

Abra el debug log, que registra qué hooks coincidieron. Un hook que se ejecutó aparece allí con su código de salida.

`Plugin directory does not exist: <path>`

Ejecuta primero /reload-plugins en el prompt de Claude Code, aunque el mensaje diga que reinstales. Un hook de plugin falla con Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall), y el hook no se ejecuta, cuando el directorio desde el que tu sesión cargó los hooks del plugin ya no existe en el disco. Plugin directory not found at path: <path> es un mensaje diferente, sobre una entrada de marketplace. La recarga carga los hooks del plugin desde su directorio actual. El fallo se muestra una vez por sesión para cada evento y comando de hook, así que el hecho de que el hook deje de mostrar errores no confirma la solución. En su lugar, lee la salida de la recarga:

Reloaded: sin línea de errores: los hooks del plugin ya no apuntan al directorio faltante
N errors during load. Run /plugin for details.: abre la pestaña Errors en /plugin y sigue la entrada de esta página para el mensaje que muestra
Una línea que termina con Run /reload-plugins --force to apply.: no se recargó nada y los hooks siguen fallando. Ejecuta /reload-plugins --force en el prompt de Claude Code

`Invalid MCP server config for "<server>"` and MCP servers that don’t start

Un plugin agrupa un servidor MCP, y la pestaña Errors muestra Invalid MCP server config for "<server>": <error>, o el servidor está listado pero /mcp nunca lo muestra conectado.

`Invalid MCP server config for "<server>": <error>`

La configuración del servidor pasa la verificación del esquema, pero Claude Code no puede resolverla para esta sesión. El texto después de los dos puntos nombra la causa y decide la solución:

Missing environment variables: <names>: establezca esas variables en el shell desde el que inicia Claude Code, luego inicie una nueva sesión
URL is unset or invalid: una opción ${user_config.*} que usa la URL no está establecida. Ejecute /plugin configure <plugin> para establecerla
has an invalid MCP url o headersHelper for MCP server '<server>' references ${user_config.*}: la configuración del plugin en sí es culpable. Corrija la url o headersHelper en la configuración MCP de su plugin, o infórmelo al autor del plugin si el plugin no es suyo. El caso headersHelper tiene su propia entrada bajo plugin command references user_config

`Bundled MCP server "<name>" was not started: it needs configuration`

El plugin incluye el servidor como un MCPB bundle que declara user_config, y una configuración requerida no tiene un valor guardado aún o un valor guardado falla la validación propia del bundle, por lo que Claude Code omite iniciar el servidor. El resto del plugin funciona. Seleccione el plugin en la pestaña Installed de /plugin y elija Configure para proporcionar los valores. Después de guardar, /plugin muestra Configuration saved. y se cierra, y Claude Code recarga plugins como se describe bajo Manage installed plugins. El servidor se inicia una vez que esa recarga se aplica. Antes de v2.1.285, Claude Code omitía el servidor sin mostrar esta línea.

Server is configured but never connects

Ejecute /mcp para ver el estado del servidor. Cuando el servidor es saludable, /mcp lo enumera como conectado. Para leer el error que el servidor imprimió mientras se iniciaba, ejecute claude --debug y abra el registro en ~/.claude/debug/<session-id>.txt. El indicador --debug no imprime en la terminal. Una entrada de servidor en .mcp.json que falla el esquema no aparece en la pestaña Errors. Claude Code descarta ese servidor y registra Invalid MCP server config for <server> in <path> solo en ese registro de depuración. Para encontrar la entrada sin cargar el plugin, ejecute claude plugin validate en su shell en el directorio del plugin, que lo informa como un error. Antes de v2.1.281, claude plugin validate no verificaba .mcp.json.

Server works with `--plugin-dir` but fails after install

Usted es el autor del plugin, y el servidor se inicia cuando carga el plugin desde su directorio de fuente con --plugin-dir pero falla una vez que el plugin está instalado. Claude Code copia un plugin instalado en su caché, por lo que una ruta que solo funciona desde el directorio de fuente se rompe. Escriba rutas dentro del plugin con ${CLAUDE_PLUGIN_ROOT}. Para rutas que alcanzan fuera del directorio del plugin, vea Files the plugin references outside its directory aren’t found.

Language server doesn’t start, uses too much memory, or reports wrong diagnostics

Instaló un code intelligence plugin y Claude no ve diagnósticos, o el servidor de lenguaje está usando demasiada memoria o reportando errores que no son reales.

Language server doesn’t start

El plugin se conecta a un binario de servidor de lenguaje que instala por separado, y Claude Code lo genera por nombre desde su PATH. La pestaña /plugin Errors muestra el fallo con su razón, como Executable not found in $PATH: "<binary>", y claude --debug lo registra como LSP server <name> failed to start: <reason>. Instale el binario y confirme que está en el PATH del terminal desde el que inicia claude, por ejemplo con which typescript-language-server. Luego inicie una nueva sesión.

Language server uses too much memory

Los servidores de lenguaje como rust-analyzer y pyright indexan todo el proyecto. Deshabilite el plugin con /plugin disable <plugin> en una sesión y confíe en las herramientas de búsqueda integradas de Claude en su lugar.

False positive diagnostics in a monorepo

Un servidor de lenguaje que no está configurado para el espacio de trabajo puede reportar importaciones no resueltas para paquetes internos. No hay nada que corregir en el lado de Claude Code, y los diagnósticos no impiden que Claude edite código.

Crear un plugin

Estás desarrollando un plugin y cargándolo con --plugin-dir o instalándolo desde un marketplace local. Estas entradas cubren los fallos que encuentras mientras desarrollas un plugin. Para las verificaciones que debes ejecutar después de cada cambio, consulta Probar y depurar. Dos fallos que también afectan a los usuarios de un plugin tienen sus entradas en El plugin está instalado pero no funciona:

Un hook que no se dispara: consulta hooks que no se disparan
Un servidor MCP que no se inicia: consulta servidores MCP que no se inician

`commands path not found: <path>`

La pestaña Errors muestra commands path not found: <absolute path> con la indicación Check that the path in your manifest or marketplace config is correct. El mismo mensaje aparece para skills, agents y hooks. Claude Code resolvió una ruta de tu plugin.json o de tu entrada del marketplace respecto a la raíz del plugin y no encontró nada allí. La ruta del mensaje es la ruta absoluta que verificó, así que compárala con lo que hay en el disco. Corrige la ruta o crea el directorio y luego ejecuta /reload-plugins. Las rutas del manifiesto son relativas a la raíz del plugin y comienzan con ./. Una ruta que se resuelve fuera de la raíz del plugin se informa como <component> path escapes plugin directory y se descarta.

`--plugin-dir` en la raíz de un marketplace no carga los plugins de `plugins/`

Iniciaste claude --plugin-dir <path> y no ves ningún error, pero los skills, agentes y hooks del plugin no aparecen. --plugin-dir recibe el directorio raíz del plugin, el que contiene .claude-plugin/plugin.json y los directorios de componentes como skills/. Si en su lugar lo apuntas a la raíz de un marketplace, Claude Code no lee marketplace.json, por lo que un plugin dentro de plugins/ no se carga y no ves ningún error. Antes de la v2.1.281, Claude Code cargaba la raíz de un marketplace como un único plugin vacío con el nombre de ese directorio. Apunta el flag al directorio del plugin en sí:

claude --plugin-dir ./my-marketplace/plugins/my-plugin

Luego abre Installed en /plugin, donde el panel de detalles del plugin enumera sus componentes.

No se encuentran los archivos que el plugin referencia fuera de su directorio

Un plugin funciona desde su directorio de origen con --plugin-dir pero falla después de instalarlo, con errores sobre una ruta como ../shared-utils. Claude Code copia un plugin instalado en su caché y lo carga desde allí, por lo que una ruta que sale del directorio propio del plugin no apunta a nada en la caché. Mueve los archivos compartidos dentro del directorio del plugin o haz referencia a ellos mediante un enlace simbólico dentro de él. Para saber dónde está la caché y cómo se resuelven las rutas, consulta Encontrar plugins en el disco.

`${CLAUDE_PLUGIN_ROOT}` muestra barras diagonales en Windows

En Windows, un hook de plugin recibe ${CLAUDE_PLUGIN_ROOT} como C:/Users/you/... en lugar de C:\Users\you\..., y un script que esperaba barras invertidas falla. Claude Code ejecuta los hooks en forma de shell a través de Git Bash en Windows y sustituye a propósito la raíz del plugin en la forma Win32 con barras diagonales. Los builtins de Bash, las herramientas de MSYS y los binarios nativos de Windows aceptan esa forma. Si tu script necesita barras invertidas, cambia el hook a una de las formas que conservan las rutas nativas, descritas en forma exec y forma de shell:

Un hook en forma exec, que inicia el proceso directamente con un arreglo args
Un hook con "shell": "powershell"

El plugin se carga pero faltan sus skills

Tu plugin aparece en Installed sin errores, pero sus skills no se ofrecen cuando escribes /. Los skills se cargan desde skills/ en la raíz del plugin y los comandos desde commands/ en la raíz del plugin. Solo plugin.json va dentro de .claude-plugin/, y un directorio skills/ dentro de .claude-plugin/ no se escanea. Mueve los directorios a la raíz del plugin y ejecuta /reload-plugins. Después, el panel de detalles del plugin en /plugin enumera los skills, y al escribir / se ofrecen. Cada skill es un directorio que contiene SKILL.md. Una entrada skills en el manifiesto que apunta a un archivo SKILL.md en lugar de a su directorio se informa como path is a file; skills entries must be directories containing SKILL.md.

El skill se carga pero Claude nunca lo invoca

El skill de tu plugin se ejecuta cuando escribes su comando /<plugin>:<skill>, pero Claude nunca lo invoca en respuesta a una solicitud normal. Revisa estas causas en orden:

El skill establece disable-model-invocation: true: el skill de plantilla de Crear tu primer plugin lo establece. Elimina la línea de un skill que quieras que Claude invoque por su cuenta. Controlar quién invoca un skill explica el campo
La descripción no coincide con la forma en que la gente pregunta: sigue las verificaciones de El skill no se activa
La descripción está truncada: cuando hay muchos skills instalados, Claude Code acorta las descripciones para ajustarlas al presupuesto de caracteres del listado, lo que puede eliminar las palabras clave que Claude necesita para relacionarlo con una solicitud. Consulta Las descripciones de los skills se recortan

Para medir con qué frecuencia se activa el skill en prompts realistas en lugar de revisarlos uno por uno, escribe un caso de eval con un grader tool_used: Skill y ejecútalo con claude plugin eval después de cada cambio en la descripción.

`<directory> is not a plugin or skill folder` al ejecutar `claude plugin eval init`

Ejecutaste claude plugin eval init desde un directorio que no es la raíz de un plugin, como tu directorio home o la raíz de un repositorio que guarda el plugin en un subdirectorio. init escribe la suite dentro del directorio de trabajo, por lo que se detiene en lugar de crear un directorio evals/ que el plugin nunca vería. Cambia a la raíz del plugin, el directorio que contiene .claude-plugin/plugin.json o el SKILL.md del skill, y vuelve a ejecutar el comando. Para generar la suite en otro lugar a propósito, pasa --eval-dir. Consulta Probar plugins con evals.

El diálogo de `userConfig` nunca aparece

Tu plugin declara opciones userConfig, pero no aparece ningún diálogo de configuración cuando lo instalas. Que la instalación pida los valores depende de dónde la ejecutes:

/plugin install en una sesión, o la pestaña Discover en /plugin: el diálogo forma parte de esta instalación interactiva
El diálogo Manage plugins de la extensión de VS Code: pide las opciones sin establecer en un formulario después de la instalación. Antes de la v2.1.285, la instalación desde allí no mostraba ningún formulario de opciones, así que establece los valores desde una sesión en la terminal con /plugin configure <plugin>@<marketplace>
claude plugin install en tu shell: nunca pide valores de userConfig. Guarda los valores --config KEY=VALUE que pases y, cuando quedan opciones sin establecer, imprime N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE. Cuando alguna de las opciones sin establecer es obligatoria, (M required) aparece después de not yet set.

Si instalaste desde el shell, pasa los valores con --config, un flag por opción:

claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

Cuando todas las opciones están establecidas, la salida de la instalación no incluye ninguna línea not yet set. Para abrir el diálogo más tarde, ejecuta /plugin configure my-plugin@my-marketplace en una sesión. Desde el shell, claude plugin configure muestra qué opciones siguen sin establecer y guarda los valores que le envíes por stdin. Requiere Claude Code v2.1.285 o posterior. Si pasas una clave --config que el manifiesto no declara, el plugin se instala de todos modos y el comando imprime ⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig. seguido de las claves que el plugin sí declara. Para un plugin que incluye un archivo de paquete MCPB que declara su propio user_config, el mensaje dice isn't declared in this plugin's userConfig or by its bundled MCP servers. en su lugar, y las claves conocidas incluyen las de ese servidor, escritas como <server>.<key>. Un paquete que el manifiesto referencia por URL no se lee durante la instalación, por lo que sus claves no se enumeran y el mensaje indica que lo configures en /plugin. Establecer claves <server>.<key> requiere Claude Code v2.1.285 o posterior.

`claude plugin validate` informa errores

Ejecutaste claude plugin validate <path>, o /plugin validate <path> en una sesión, e imprimió Found N errors y Validation failed, y luego terminó con el código 1. El validador lee el manifiesto en la ruta que le indicas: .claude-plugin/plugin.json para un directorio de plugin, .claude-plugin/marketplace.json para un directorio de marketplace, o ambos para un directorio que contiene ambos. Para un marketplace, antepone a los problemas del manifiesto propio de una entrada el índice de la entrada, como en plugins[1] plugin.json → json: .... Antes de la v2.1.289, Claude Code validaba un directorio que contiene ambos solo como marketplace. La tabla cubre los mensajes que detienen la validación y dos advertencias, No frontmatter block found y Unknown field '<key>', que la detienen solo cuando pasas --strict. Otras advertencias, como la falta de una descripción, no se incluyen.

Mensaje	Causa	Solución
`File not found: <path>`	La ruta no tiene manifiesto o no existe.	Ejecuta el comando sobre la raíz del plugin o del marketplace, el directorio que contiene `.claude-plugin/`.
`No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json`	El directorio no tiene un manifiesto `.claude-plugin/`.	Crea el manifiesto o apunta al directorio correcto.
`Invalid JSON syntax: <parse error>`	El manifiesto, o `hooks/hooks.json`, no es JSON válido.	Corrige el JSON. Hasta que corrijas `hooks/hooks.json`, una sesión carga el plugin sin los hooks de ese archivo.
`Path not found: <path>. The runtime loader will report this as a load failure.`	Una ruta de componente del manifiesto no existe.	Corrige la ruta o crea el directorio.
`Path contains ".." which could be a path traversal attempt: <path>`	Una ruta de componente sale del directorio del plugin.	Usa rutas dentro de la raíz del plugin.
`Path is a file; skills entries must be directories containing SKILL.md`	Una entrada `skills` apunta a `SKILL.md` en lugar de a su directorio.	Apunta al directorio padre, o a `.` para un `SKILL.md` en la raíz.
`No frontmatter block found` o `YAML frontmatter failed to parse: <error>`	Un archivo de skill, agente o comando tiene frontmatter YAML faltante o no válido.	Agrega o corrige el frontmatter entre delimitadores `---`. Se informa al validar un directorio de plugin.
`Plugin name "<name>" is reserved: it passes as one of Anthropic's own`	El `name` del plugin es uno de los nombres reservados.	Cambia el nombre del plugin según lo que hace.
`Unknown field '<key>'`	El manifiesto tiene un campo que el esquema no define.	Elimínalo o usa el nombre que sugiere el mensaje. Claude Code ignora los campos desconocidos al cargar. Para `privacyPolicyUrl` y los demás campos de listado del directorio en `plugin.json`, consulta Campos de listado del directorio.

Vuelve a ejecutar el comando después de cada corrección hasta que no imprima errores. Los campos de plugin.json están en la referencia del manifiesto, y los mensajes a nivel de marketplace están en Errores de validación del marketplace.

`Plugin <name> has conflicting manifests`

El plugin no se carga y muestra Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components. El plugin tiene su propio plugin.json, y su entrada del marketplace establece strict: false y además declara alguno de commands, agents, skills, hooks, outputStyles o themes. Elimina esos campos de la entrada, o establece strict: true en la entrada para que Claude Code los agregue a plugin.json. Consulta Modo estricto.

`Warning: No commands found in plugin <name> custom directory`

Cuando el plugin se carga, el registro de claude --debug en ~/.claude/debug/<session-id>.txt registra Warning: No commands found in plugin <name> custom directory: <path>. Expected .md files or SKILL.md in subdirectories. No aparece nada en la sesión ni en la pestaña Errors. La ruta commands del manifiesto existe pero no contiene archivos .md ni ningún SKILL.md en un subdirectorio. Agrega los archivos de comando o elimina la ruta del manifiesto.

Host a marketplace

Publica un mercado y un usuario informa un error, o su propia validación falla. Estas entradas son para el propietario del mercado.

Plugins with relative paths fail in URL-based marketplaces

Los usuarios agregaron su mercado con una URL https://example.com/marketplace.json. Las instalaciones de plugins cuya source es una ruta relativa, como ./plugins/my-plugin, fallan con its marketplace entry path does not stay inside the marketplace directory. Los plugins ya instalados fallan al cargar con Plugin source path refused. Ambos mensajes tienen una entrada de referencia de error. Cuando un usuario agrega un mercado basado en URL, Claude Code descarga solo el archivo marketplace.json en sí. No obtiene archivos de plugin por ruta relativa desde ese servidor, por lo que una ruta relativa en una entrada apunta a un directorio que nunca fue obtenido. Dé a cada entrada una fuente que Claude Code pueda obtener por su cuenta, como un repositorio de GitHub:

{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

Alternativamente, aloje el mercado en un repositorio git y diga a los usuarios que lo agreguen con la URL del repositorio. Para una fuente de git, Claude Code clona todo el repositorio, por lo que las rutas relativas se resuelven. Los tipos de fuente están en la marketplace reference.

Marketplace validation errors

Ejecutó claude plugin validate . desde su directorio de mercado e informó errores o advertencias en el archivo del mercado en sí. claude plugin validate también valida cada entrada cuya source es una ruta local y advierte cuando la version de la entrada no coincide con el manifiesto propio del plugin. La tabla enumera los mensajes a nivel de mercado. Los mensajes a nivel de entrada son los mensajes de plugin bajo claude plugin validate reports errors, prefijados con plugins[N] plugin.json →.

Mensaje	Tipo	Solución
`Duplicate plugin name "<name>" found in marketplace`	Error	Dé a cada plugin un `name` único.
`Path contains "..": <path>` bajo `plugins[N].source`	Error	Use rutas relativas a la raíz del mercado sin segmentos `..`.
`Marketplace name cannot contain control or bidirectional-formatting characters`	Error	Elimine el carácter del nombre, como un escape o una nueva línea.
`Plugin name cannot contain control or bidirectional-formatting characters`	Error	Elimine el carácter del `name` del plugin.
`Claude Code cannot install plugins from marketplace "<name>". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".`	Error	Cambie el nombre del mercado para que se ajuste a la regla que indica el mensaje.
`Claude Code cannot install plugin "<name>". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".`	Error	Cambie el nombre de la entrada para que se ajuste a la regla que indica el mensaje.
`Marketplace has no plugins defined`	Advertencia	Agregue al menos una entrada a `plugins`.
`No marketplace description provided`	Advertencia	Agregue una `description` a nivel superior.
`Plugin name "<name>" is not kebab-case` bajo `plugins[N] plugin.json → name`	Advertencia	Cambie el nombre a letras minúsculas, dígitos, y guiones; la sincronización del mercado de claude.ai requiere esa forma.
`Entry declares version "<a>" but <path>/plugin.json says "<b>"`	Advertencia	Actualice la entrada para que coincida con `plugin.json`, que es autoritario en el tiempo de instalación.
`Marketplace name "<name>" is reserved in Claude Desktop`	Advertencia	Cambie el nombre del mercado. La sincronización de mercado administrada de Claude Desktop rechaza `org`, `org-provisioned`, y `unknown` en cualquier mayúscula.
`Marketplace name "<name>" is not accepted by Claude Desktop` o `Plugin name "<name>" is not accepted by Claude Desktop`	Advertencia	Cambie el nombre a como máximo 128 caracteres de letras, dígitos, `.`, `_`, y `-`, comenzando con una letra o dígito.

Antes de v2.1.247, un nombre de mercado que contiene caracteres de control o de formato bidireccional se informaba solo como Marketplace name impersonates an official Anthropic/Claude marketplace.

Blocked by your organization

Su organización implementa configuración administrada que restringe plugins, y un comando fue rechazado con un mensaje de política. Estas entradas nombran la configuración detrás de cada rechazo para que sepa qué pedir a su administrador. Para el lado del administrador, vea Manage plugins for your organization.

`Marketplace source '<source>' is blocked by enterprise policy`

Ejecutó /plugin marketplace add, update, o una instalación, y Claude Code rechazó con esta línea. Para una fuente de GitHub o git, el host sigue la fuente entre paréntesis, como en 'github:owner/repo' (github.com). Su administrador estableció blockedMarketplaces o strictKnownMarketplaces en configuración administrada, y esta fuente no está permitida. Pida a su administrador que permita la fuente, o agregue una de las fuentes permitidas que el mensaje enumera. Haga coincidir el resto del mensaje para ver qué tipo de política bloqueó la fuente:

Allowed sources: <list>: el bloqueo proviene de la lista de permisos strictKnownMarketplaces en lugar de la lista de bloqueos blockedMarketplaces
No external marketplaces are allowed.: la lista de permisos strictKnownMarketplaces está vacía
Un Tip: que el atajo asume github.com: la lista de permisos permite un host de git por nombre de host, y el atajo owner/repo que pasó apunta a github.com. Si el repositorio vive en su host interno, agréguelo nuevamente con su URL completa, como git@your-git-host.com:owner/repo.git

Un mercado que agregó antes de que la política se volviera más restrictiva también deja de actualizarse, porque la política se aplica en cada actualización.

`Marketplace "<name>" is not in the allowed marketplace list`

La pestaña Errors muestra esta línea, o Marketplace "<name>" is blocked by enterprise policy, para un mercado que ya tiene registrado. La misma configuración administrada que bloquea una marketplace source se aplica en el tiempo de carga. strictKnownMarketplaces no incluye este mercado, o blockedMarketplaces lo nombra, por lo que Claude Code deja de cargarlo y sus plugins. Para la variante de lista de permisos, la línea de orientación muestra las fuentes permitidas, o Contact your administrator to configure allowed marketplace sources. Para la variante de lista de bloqueos dice This marketplace source is explicitly blocked by your administrator.

`Plugin "<name>" is blocked by your organization's policy and cannot be installed`

Una instalación fue rechazada con esta línea, una habilitación con la misma línea terminando cannot be enabled, o una instalación o actualización con una que nombra la razón: Plugin "<name>" is from marketplace "<marketplace>", which is blocked by your organization's policy, o Plugin "<name>" depends on "<dep>", which is blocked by your organization's policy. La configuración administrada bloquea este plugin, su mercado, o una dependencia que necesita. Pida a su administrador qué entrada se aplica. Una dependencia bloqueada significa que el plugin no puede instalar hasta que el mercado de la dependencia sea permitido.

`--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)`

Inició claude con --plugin-dir, --plugin-url, --agents, o --mcp-config. Claude Code salió con este mensaje y Plugins, custom agents, and MCP servers can only be loaded from sources your administrator has approved. Su administrador estableció disableSideloadFlags en configuración administrada, que desactiva los indicadores que cargan plugins, agents, y servidores desde rutas arbitrarias. Cargue el plugin desde un mercado aprobado en su lugar, o pida a su administrador que elimine la configuración. Un mensaje relacionado en la pestaña /plugin Errors es --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings. La configuración administrada habilita o deshabilita ese plugin por nombre, y Claude Code ignora su copia --plugin-dir de él para que el indicador no pueda anular la política.

`Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`

Ejecutó claude plugin init o claude plugin enable, y se detuvo con esta línea. El mensaje nombra strictKnownMarketplaces or blockedMarketplaces y pide a su administrador que agregue {"source":"skills-dir"} a strictKnownMarketplaces o lo elimine de blockedMarketplaces. La fuente skills-dir representa plugins que Claude Code carga desde su directorio ~/.claude/skills/. Pida a su administrador que haga el cambio que el mensaje nombra.

`Command-sourced plugins are disabled by your organization's managed settings`

Instaló o actualizó un plugin con una fuente command, y se detuvo con esta línea y The plugin was not installed or updated and its command was not run. Su administrador estableció disableCommandPluginSources, por lo que Claude Code rechaza ejecutar el comando declarado por mercado que produce el plugin. Establecer allowManagedHooksOnly solo tiene el mismo efecto cuando disableCommandPluginSources no está establecido. Pida a su administrador si el plugin puede publicarse desde un tipo de fuente que la política permite.

`Marketplace '<name>' is seed-managed`

Ejecutó claude plugin marketplace update <name>, y falló con Marketplace '<name>' is seed-managed (<dir>) y una sugerencia para pedir a su administrador. Un operador pre-rellenó este mercado a través de CLAUDE_CODE_PLUGIN_SEED_DIR, y Claude Code trata un mercado administrado por semilla como de solo lectura. Una marketplace update masiva lo omite y actualiza los otros. Para cambiar el contenido del mercado, pida a la persona que mantiene la imagen de semilla que lo actualice. Para el procedimiento, vea Seed containers and CI.

Next steps

Plugin loading reference: por qué los scopes, la caché, y la precedencia se comportan de la manera que lo hacen
Plugin commands reference: indicadores, valores predeterminados, salida, y códigos de salida para los comandos claude plugin
Install and manage plugins: los pasos de instalación desde el principio
Manage plugins for your organization: solución de problemas del lado de la política para administradores

​Find where /plugin runs

​/plugin isn't available in this environment

​zsh: no such file or directory: /plugin

​The term '/plugin' is not recognized as the name of a cmdlet

​claude: command not found after claude plugin ...

​Unknown command and command spellings that don’t exist

​Add a marketplace

​Marketplace "claude-plugins-official" not found

​Marketplace "<name>" not found

​Invalid marketplace source format

​'<source>' is not a valid GitHub owner/repo shorthand

​Invalid git URL

​Path does not exist: <path>

​Marketplace file not found at <path>/.claude-plugin/marketplace.json

​Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name

​Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it

​SSH authentication failed or HTTPS authentication failed

​SSH host key is not in your known_hosts file

​Command 'git' not found or is in an unsafe location

​Git clone timed out after 120s

​Marketplace updates keep failing offline

​Marketplace add fails on a GitHub Enterprise Server host

​Instalar un plugin

​Plugin "<name>" not found in marketplace "<marketplace>"

​not found in marketplace con una sugerencia de actualización

​not found in marketplace sin sugerencia

​Plugin "<name>" not found in any marketplace

​Plugin '<name>@<marketplace>' is already installed globally

​"<plugin>" was not installed: it would share its folder with "<other>"

​This plugin uses a source type your Claude Code version does not support

​Plugin archive integrity check failed

​An npm plugin source must name a registry package

​Marketplace "<name>" is registered from an untrusted source

​Marketplace "<name>" is added but ignored

​Plugin <name> has a corrupt manifest file o has an invalid manifest file

​Plugin directory not found at path: <path>

​No plugins available o No marketplaces configured

​Marketplace "<name>" is already added from a different source

​Cannot add marketplace "<name>": its source doesn't match its extraKnownMarketplaces entry in user or managed settings

​Failed to install: <plugin> (<reason>)

​Could not move the new copy of this plugin version into <path>

​Errores de dependencias

​Plugin installed but not working

​Plugin doesn’t appear or its skills don’t show up

​Run /reload-plugins to apply.

​The packages it lists are not installed o were not installed, because ...

​Plugin "<name>" not cached at <path>

​installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read

​installed_plugins.json could not be read and was rebuilt

​install records under names that no version of Claude Code can use were removed from installed_plugins.json

​does not load (...), so Claude Code ignores the whole file

​Disabled in ~/.claude/settings.json but still loads

​Plugin "<name>" is enabled in project settings but isn't installed here

​Un plugin sigue instalado después de plugin uninstall en Windows

​Failed to load hooks from <path> and hooks that don’t fire

​Hooks fail to load

​hook error notices in the transcript

​A plugin hook blocks a tool call or prompt

​Hook loads but never fires

​Plugin directory does not exist: <path>

​Invalid MCP server config for "<server>" and MCP servers that don’t start

​Invalid MCP server config for "<server>": <error>

​Bundled MCP server "<name>" was not started: it needs configuration

​Server is configured but never connects

​Server works with --plugin-dir but fails after install

​Language server doesn’t start, uses too much memory, or reports wrong diagnostics

​Language server doesn’t start

​Language server uses too much memory

​False positive diagnostics in a monorepo

​Crear un plugin

​commands path not found: <path>

​--plugin-dir en la raíz de un marketplace no carga los plugins de plugins/

​No se encuentran los archivos que el plugin referencia fuera de su directorio

​${CLAUDE_PLUGIN_ROOT} muestra barras diagonales en Windows

​El plugin se carga pero faltan sus skills

​El skill se carga pero Claude nunca lo invoca

​<directory> is not a plugin or skill folder al ejecutar claude plugin eval init

​El diálogo de userConfig nunca aparece

​claude plugin validate informa errores

​Plugin <name> has conflicting manifests