Saltar al contenido principal

Problemas comunes con los plugins Claude — troubleshooting

Si buscas cómo usar los plugins en el día a día, ver uso-plugins-claude-para-usuarios o uso-plugins-claude-desarrollo.

💡 Los comandos que empiezan con / (como /reload-plugins) se escriben dentro del chat de Claude Code. Los que empiezan con claude (como claude plugin list) se escriben en la terminal de tu sistema — son dos lugares distintos.

Un plugin sale "failed to load"​

Lo más común: una dependencia no se autoinstaló. Cuando wiedii-dev se actualiza a una versión que agregó plugins (p. ej. se sumó security-guidance), Claude Code no los instala en silencio → el plugin queda "failed to load (Dependency X not installed)".

Cómo resolverlo (no instales nada a mano):

  1. Reinicia Claude Code (terminal o panel Code de Desktop) → resuelve e instala todas las dependencias faltantes de una sola pasada. ← lo más rápido.
  2. Alternativa sin reiniciar: /reload-plugins — pero ⚠️ resuelve una dependencia por recarga; si faltan varias, repite hasta que claude plugin list no muestre errores.
  3. Verifica con claude plugin list o /doctor que ya no haya "failed to load".

Si tras reiniciar sigue faltando algo (o ves errores que no son de Wiedii, p. ej. MCP de un plugin oficial) → escríbele al TL (responsable de la implementación de IA).

Ves el mismo plugin varias veces (instancias duplicadas)​

Si en /plugin o en el panel de Desktop el mismo plugin aparece dos o tres veces, el marketplace de Wiedii quedó definido por varias vías a la vez en tu máquina. Lo normal es que solo lo provea el TL por managed settings; los duplicados aparecen cuando además quedó un /plugin marketplace add manual o un bloque en tu ~/.claude/settings.json de una instalación vieja. Cada definición instancia el plugin → se ve repetido.

¿No te sientes cómodo editando archivos de configuración a mano? Escríbele al TL y te lo deja limpio — no hace falta que sigas los pasos de abajo tú mismo, y no borres cosas dentro de ~/.claude/plugins/ a mano.

Cómo dejar una sola instancia:

  1. Abre ~/.claude/settings.json (el archivo de configuración de Claude Code en tu máquina) y borra cualquier extraKnownMarketplaces que repita claude-wiedii-plugins (lo provee el TL por managed) y las líneas de enabledPlugins de wiedii-core (ya es obligatorio por managed). Deja solo tu instalación de wiedii-dev, si lo usas.
  2. Reinicia Claude Code (o /reload-plugins, dentro del chat).
  3. Verifica en /plugin → Marketplaces (dentro del chat): claude-wiedii-plugins debe salir una sola vez, y cada plugin una vez.
  4. Si sigue duplicado: escribe /plugin marketplace remove claude-wiedii-plugins (dentro del chat) y reinicia (el TL lo vuelve a registrar solo); reinstala wiedii-dev si lo usabas.

Referencias viejas en el cache​

Cada vez que un plugin se actualiza, su versión anterior queda en tu cache local (~/.claude/plugins/cache/…). Es normal y Claude Code lo limpia solo: las versiones huérfanas se borran a los 7 días. No tienes que hacer nada.

Si quieres ordenar de vez en cuando:

  • claude plugin prune — quita las dependencias auto-instaladas que ya ningún plugin necesita. Es seguro (no toca los plugins que instalaste tú) y es lo único que conviene correr a mano.
  • Las versiones viejas del cache: déjalas — el barrido de 7 días las purga; no las borres a mano (podrías eliminar la versión activa).

(Esto es solo para Claude Code; en Cowork no hay cache local que mantener — lo gestiona la organización.)

"El marketplace no está registrado" en Claude Code (CLI o panel Code de Desktop)​

A diferencia de "failed to load" (una dependencia no se autoinstaló), este error significa que tu Claude Code no recibió el bloque de managed settings que el TL configuró a nivel de organización — el marketplace claude-wiedii-plugins nunca llegó a registrarse en tu máquina. Revisa en este orden:

  1. /status (dentro del chat) — confirma si la fuente activa de configuración es managed settings. Si no lo es, los settings simplemente no te están llegando.

  2. La cuenta con la que iniciaste sesión — tiene que ser el login de la organización de Wiedii, no una cuenta personal de Claude. Los managed settings de la organización no se entregan a cuentas fuera de ella.

  3. Variables de entorno de proveedor — en tu terminal: env | grep -E "ANTHROPIC_BASE_URL|CLAUDE_CODE_USE_". Si cualquiera de estas tiene un valor (aunque venga heredada de un .zshrc/.bashrc viejo o de una plantilla de otro proyecto), Claude Code se salta por completo la descarga de managed settings para esa sesión — hay que quitarla del shell.

  4. Reinicio completo — los managed settings se aplican recién en el próximo arranque o en el chequeo cada hora, nunca a mitad de sesión. Confirma que cerraste el proceso entero (no solo la ventana) después del último cambio que te avisaron.

  5. Versión de Claude Code — mantenla actualizada; varias partes de este comportamiento cambiaron entre versiones recientes.

  6. Si nada de esto lo explica, se puede generar un archivo de diagnóstico (un "debug log") para que el TL lo revise. Es un archivo temporal — no hace falta guardarlo, por eso lo generamos en la carpeta temporal del sistema y no en tu carpeta de usuario. Es un poco más largo de explicar porque usa la terminal (la aplicación de texto donde se escriben comandos, distinta a la ventana de chat de Claude), así que va paso a paso pensando en que nunca la usaste:

    a. Abrí una aplicación de terminal — en Wiedii se usa la app Terminal que ya viene instalada en Mac, o Warp (otra app de terminal, si es la que tenés instalada; hacen lo mismo). Para abrir cualquiera de las dos: presioná Cmd + Espacio (la barra espaciadora con la tecla Cmd), escribí Terminal (o Warp, según cuál uses) y presioná Enter. Se abre una ventana con texto (fondo claro u oscuro según tu configuración) y un cursor parpadeando — ahí es donde vas a escribir los siguientes comandos.

    b. Escribí (o copiá y pegá) exactamente esto y presioná Enter:

    claude --debug-file /tmp/claude-debug.log

    ⚠️ Este comando abre una sesión nueva de Claude Code — vas a ver aparecer el chat normal de Claude, como si lo estuvieras iniciando por primera vez. Es lo esperado, no es un error. No hace falta escribirle nada a Claude ahí ni hacerle ninguna pregunta.

    c. Para cerrar esa sesión y volver a la terminal, escribí:

    exit

    y presioná Enter. Este paso es obligatorio — el archivo de diagnóstico no queda completo hasta que salís así. Si en cambio cerrás la ventana de la terminal con la ❌ (la equis), el archivo puede quedar incompleto o vacío.

    d. Ya de vuelta en la terminal (fuera de Claude), escribí este comando y presioná Enter — busca, dentro del archivo que se generó, solo la parte que nos interesa, sin necesidad de abrir el archivo entero (que puede tener miles de líneas):

    grep -i "remote settings" /tmp/claude-debug.log

    Esto va a imprimir en pantalla únicamente las líneas que mencionan "remote settings" (puede que no aparezca ninguna línea — también es información útil).

    e. Copiá solo lo que apareció en pantalla tras ese último comando (el resultado del grep) y compartilo con el TL — no el archivo completo. El archivo entero puede contener tokens u otros datos de tu sesión que no deben compartirse. Si en lo que copiaste ves la palabra Authorization o token seguida de una cadena larga de letras y números, reemplazá esa parte por [oculto] antes de enviarlo, por las dudas.

    f. El archivo queda guardado en /tmp/claude-debug.log. Es temporal — el sistema lo limpia solo con el tiempo, no hace falta que lo borres a mano (pero tampoco pasa nada si lo hacés).

Nota: quién puede tocar y cómo se despliega el bloque de managed settings a nivel de organización es un tema aparte, TL-only, documentado en el repo claude-wiedii-plugins (no en este vault) — esta sección es solo para diagnosticar el síntoma del lado de tu máquina.

Relacionados​