Solución de problemas

Qué hacer cuando algo no funciona: arranque, indexado, IA, Claude Code, Git, base de datos y build.

Antes de nada, dos herramientas que ayudan siempre:

Ayuda → Registro de errores… muestra los errores recientes del IDE.
Ayuda → Reportar un problema… arma un .zip con lo necesario para diagnosticar, sin tu código ni tus conversaciones. Copiar resumen da el texto listo para pegar.

Pregúntale al agente «¿qué está fallando?». Con yuli_health revisa problemas, ejecución, pruebas, terminales y registros de Yuli de una vez.

Instalación y arranque

Síntoma	Qué hacer
Windows advierte al ejecutar el instalador	Comprueba que lo descargaste de la fuente oficial y que el editor del certificado es «Yuli Code».
El AppImage no abre en Linux	Dale permiso de ejecución con `chmod +x`.
El portable tarda la primera vez	Es normal: descomprime la aplicación una vez por versión. Después arranca al instante.
La interfaz está en otro idioma	Opciones globales → Apariencia → Idioma. Ver Idiomas.
Quieres medir por qué tarda en arrancar	Ayuda → Rendimiento de arranque….

Síntoma	Qué hacer
Faltan referencias o la navegación es incompleta	Espera a que termine el indexado (barra superior del editor).
Lombok o las dependencias no se resuelven	El proyecto puede estar en modo restringido. Opciones globales → Seguridad → Proyectos de confianza → Confiar.
Aviso «Sin servidor de lenguaje para…»	Pulsa Instalar… y autoriza la descarga.
El índice parece desactualizado	Herramientas → Limpiar caché… borra índices y estado guardado; Yuli los regenera.
Falta un JDK, Maven o Gradle	Yuli ofrece descargarlo. Configúralo en Proyecto → Build, ejecución y depuración….

Síntoma	Qué hacer
Error de autenticación en Modo Platform	Revisa la API key en la configuración del modelo y pulsa Probar conexión.
Un modelo local no contesta	Comprueba que el servidor esté corriendo y que la URL del servidor sea correcta.
El proveedor está caído	Yuli respeta el `retry-after` del proveedor. Espera o cambia de proveedor.
Se detuvo una tarea en segundo plano	Llegó a su tope de tokens o costo: Ampliar límite y reanudar.
El equipo de agentes se pausó	Llegó a su presupuesto. Amplíalo en Más acciones → Equipo de agentes.

Síntoma	Qué hacer
Yuli no encuentra el agente	Instálalo con su instalador oficial y pulsa Volver a detectar.
«Esperando a que Claude Code use las herramientas de Yuli»	Aprueba el servidor `yuli` o pulsa Aprobar ahora. Revísalo con `/mcp`.
`/mcp` muestra `yuli` con error	Abre el proyecto en Yuli: las herramientas funcionan solo con Yuli abierto. `yuli_status` explica el motivo.
Las reglas no cambiaron	Se cargan al iniciar la sesión: reiníciala desde la barra del agente.
Codex dice que falta el adaptador	Instala `codex-acp`: `npm install -g @openai/codex @agentclientprotocol/codex-acp`.
Kiro pide actualizar	Yuli necesita Kiro CLI 1.28.2 o posterior.
No quiero que Yuli bloquee nada	Desactiva Hacer cumplir las reglas («Solo avisar»). Git y secretos se protegen siempre.

Síntoma	Por qué	Qué hacer
No hace commit ni push	Git solo se habilita con un pedido explícito.	Pídelo: «haz commit y push». Aprueba cada acción.
No crea una rama	Las ramas necesitan su propio pedido.	Pide la rama explícitamente.
No lee un archivo	Es un archivo de secretos (`.env`, llaves, credenciales).	Es intencional. Pasa el dato sin el secreto.
No puede escribir fuera del proyecto	El sandbox lo limita al proyecto.	Proyecto → Acceso a carpetas…
No ejecuta una sentencia en la base	La conexión no tiene Super permisos para esa clase.	Ajusta el Acceso del agente de la conexión.
No pasa a Pruebas	La medición está pendiente o pidió iterar.	Mira la pestaña Medición del panel Calidad.
No termina el turno	Falta la verificación en verde.	Mira qué falla en Ejecución, Tests o Problemas.

Síntoma	Qué hacer
Una operación tarda demasiado	Al vencer el límite aparece Reintentar.
Error de certificado con un servidor interno	Marca la confianza en su certificado; Yuli recuerda la decisión por servidor.
No puedo hacer commit por el gate	Lee el control que falló (secretos, integridad de tests, tamaño, rutas protegidas). Corrígelo o pide una excepción con vencimiento.
Los hooks de Yuli no se instalaron	Ya hay otra herramienta en `core.hooksPath` (por ejemplo, husky). Yuli no la reemplaza.

Síntoma	Qué hacer
«Para conectar a Oracle falta Oracle Instant Client»	Instala Instant Client 19c o posterior y agrégalo al `PATH`.
Error de certificado	Marca Confiar en el certificado del servidor en la conexión.
El agente no ve una conexión	Su acceso está en Sin acceso.
Una consulta del agente se cortó	Superó los 45 segundos o su plan estima un recorrido demasiado grande. Acota la consulta.

Síntoma	Qué hacer
«Docker no está disponible»	Arranca Docker y pulsa Reintentar.
«kubectl no está configurado»	Instala `kubectl` y configura un contexto (kubeconfig).