Troubleshooting — los problemas más comunes y cómo arreglarlos
Esta página es una referencia, no una lección. Volvé acá cuando algo no salga como esperabas. Está ordenada por frecuencia, no por gravedad.
Si tu problema no está acá, escribinos a través de la sección de Ayuda.
🖥️ Instalación y arranque
”No me deja iniciar sesión en Claude Code”
- Cerrá sesión en claude.ai en el navegador, después volvé a iniciar sesión en la app de Claude Code. A veces se pisan las sesiones.
- Asegurate de usar la misma cuenta de Claude en los dos lados.
- Si sigue sin entrar, cerrá la app del todo (Mac:
Cmd+Q; Windows: clic derecho en la barra → Salir) y volvé a abrirla.
”La app abre en blanco / pantalla negra”
Cerrá la app por completo (Cmd+Q en Mac, clic derecho → Salir en Windows) y volvé a abrirla. El 90% de las veces se arregla así.
”¿App de escritorio o terminal?”
Si estás empezando, usá la app de escritorio (ventanas y botones, sin terminal). La CLI (npm i -g @anthropic-ai/claude-code) es opcional y para más adelante. Las dos son la misma herramienta de fondo.
”Estoy en Windows y los comandos no son iguales”
Normal: muchos ejemplos usan rutas estilo Mac. Con la app de escritorio casi nunca necesitás la terminal. Cuando una lección muestre un comando, vas a tener la versión de Windows al lado.
🧠 Memoria (CLAUDE.md)
“Claude no parece leer mi CLAUDE.md”
- El archivo se carga al empezar la sesión, no en el medio. Cerrá Claude Code y abrí una sesión nueva.
- Verificá que el archivo exista y esté guardado. En la app: Settings → Memory. En la CLI: abrí
~/.claude/CLAUDE.md. - Si guardaste cambios con la sesión abierta, no se recargan solos: empezá una sesión nueva.
”Mi CLAUDE.md es enorme y Claude ignora cosas”
Un CLAUDE.md largo rinde peor: todo se carga en cada respuesta y diluye lo importante. Mantenelo corto (menos de 200 palabras), con hechos, no aspiraciones. Si hace falta, mandá el detalle a archivos aparte y dejá el CLAUDE.md como índice.
🌐 Construir y publicar
”No se abre la preview”
Pedíselo explícito: “abrí la preview en vivo para que la vea”. Si igual no aparece, decile “levantá un servidor de desarrollo y pasame el link de localhost”.
”El deploy a Vercel falla o no sé cómo loguearme”
Dejá que Claude te guíe: “publicá esto en Vercel y guiame en cualquier paso de login de a un clic por vez”. La primera vez te va a pedir crear/iniciar la cuenta de Vercel (gratis). Si tira error, copiá el error y pegáselo a Claude: “falló el deploy, este es el error, arreglalo”.
🔌 Skills y MCPs
”Instalé un MCP pero Claude no lo ve”
- En la CLI, corré
/reload-pluginsdespués de instalar. - Si el MCP necesita login, corré
/mcpy conectá la cuenta una vez. - Confirmá con
/mcpque figure como connected.
”El MCP de GitHub no encuentra mis repos”
El error más común: te conectaste con una cuenta de prueba. Reconectá con tu cuenta real de GitHub.
”Conecté demasiados MCPs y va lento”
Cada MCP ocupa contexto. Corré /context y /mcp, desconectá los que no uses y quedate con 3-5. No instales todo “por las dudas”.
🤖 Agentes
”El agente se va por las ramas / hace de más”
- Faltó alcance: decile exactamente qué archivos/carpetas tocar y qué no hacer.
- Faltó condición de fin: agregá un final medible (“terminá cuando existan estos 3 archivos”).
- Probalo a mano varias veces antes de ponerlo en agenda. Nunca automatices algo que todavía no funcionó mirándolo.
”El agente dice que terminó pero no pasó nada”
Casi siempre es: un hook lo frenó, le faltan permisos, o la ruta está mal escrita (mayúsculas/minúsculas). Pedile que te muestre qué intentó hacer paso a paso.
⚙️ Modelos y contexto
”Se llenó el contexto / va más lento con el tiempo”
Cuando la ventana está cerca del 50%, pedile un resumen de la sesión y después corré /clear. Empezás limpio sin perder el hilo.
”¿Qué modelo uso?”
Con /model elegís. Regla simple: Opus para pensar/planificar, Sonnet para construir, Haiku para tareas chicas. Si una respuesta sale floja, probá subir de modelo.
🎬 Video (Capítulo 8)
“ElevenLabs me dice que me quedé sin créditos”
El plan gratis tiene un tope mensual. Si te quedaste corto, esperá al próximo mes o subí al plan pago más barato. No vale la pena pagar mucho al principio.
Si tu problema no está acá, consultá la sección de Ayuda para más recursos.