🧯 Troubleshooting (Desktop)

Problemas frecuentes y soluciones en Context Code Desktop. Para issues de build: /desktop/ejecucion. Para configuración: /desktop/configuracion.

---

🧩 La app no inicia o no responde

Acciones:

• Verifica que exista al menos un workspace y un chat activos.
• Revisa los permisos del chat (si está en modo ReadOnly o SafeEdit con confirmations, las tools pueden quedar esperando aprobación).
• Comprueba si la sesión quedó esperando aprobaciones (banner amarillo en la parte superior).
• Reinicia la app: tauri dev puede dejar el puerto 1420 ocupado, ejecute pnpm tauri:dev:reset.

Ver: /desktop/permisos

---

🧩 El chat "no responde nunca" o tarda demasiado

Síntomas: el botón de enviar gira indefinidamente o tarda minutos en responder.

Acciones:

• Provider/modelo incorrecto: el selector podría estar enviando un modelo que el proveedor activo no soporta. Verifica que el effectiveModel mostrado en el selector coincida con un modelo del provider (ej. claude-opus-4-8 para Anthropic). En el chat SQL: revisa que effectiveProvider esté canonicalizado en la consola.
• Timeout de red: ureq::Agent tiene timeout_read: 600s y timeout_connect: 30s. Si el LLM está colgado, la llamada puede tardar hasta 10 minutos en fallar. Comprueba tu conexión a internet.
• Falta de API key: revisa la pestaña Models del ChatConfigEditor y verifica que el provider esté marcado como ✓ Conectado.
• Variable de entorno con prioridad: si defines ANTHROPIC_API_KEY etc., tienen prioridad sobre el almacenamiento cifrado. Si esa key está vencida o es de otro entorno, el agente la usará igual.

---

🧩 "Motor core local no disponible" o "No se encontró .../context-bootstrap.js"

Síntomas:

• Automatizaciones no se ejecutan.
• Mensaje de error citando context-bootstrap.js.

Acciones:

1. Verifica que node funcione en una terminal:

   node --version

2. Verifica que exista el CLI embebido en el bundle de Tauri:

   ls apps/desktop/src-tauri/resources/CLI/

   Debe contener context-bootstrap.js y un node_modules/.

3. Si falta, recompila:

   pnpm -C apps/desktop build:cli
   pnpm -C apps/desktop sync:cli-deps

4. La CLI context global es opcional; la app funciona con el motor nativo Rust por defecto.

---

🧩 Voz / micrófono no funciona

• Windows: WebView2 debe tener permisos de micrófono. Ve a Configuración → Privacidad → Micrófono → permite acceso a la app.
• Mac: TCC debe aprobar el primer uso. Si lo rechazaste por error, ve a Preferencias del Sistema → Seguridad y privacidad → Micrófono.
• Whisper no descarga: el modelo se descarga bajo demanda (~140 MB). La primera activación puede tardar varios minutos; el evento whisper://download muestra el progreso.

Ver: /desktop/configuracion → STT.

---

🪟 Windows: particularidades

• PATH no se actualiza tras instalar Node o Rust: cierra y abre de nuevo la app/terminal para recargar variables.
• WebView2 bloqueado: algunas políticas corporativas bloquean WebView2. Verifica con Get-AppxPackage -Name Microsoft.WebView2 (debe estar instalado).
• Puerto 1420 ocupado: pnpm kill:1420 (Windows usa netstat + taskkill internamente).
• MAX_PATH en instalador: build-cli.mjs aplana @opentelemetry/* para evitar este error. Si reaparece tras actualizar deps, vuelve a correr pnpm build:cli.

---

🍎 macOS: particularidades

• App no abre por Gatekeeper: el primer launch requiere aprobar el binario (clic derecho → Abrir). Para distribuir, firma con codesign --deep --force --options runtime.
• Permisos de cámara/micrófono: gestionados por TCC. Si los rechazaste, ve a Preferencias del Sistema para restablecerlos.
• DMG/.app: generados con pnpm instaladormac o pnpm instalador:mac.

---

🐧 Linux: particularidades

• WebKitGTK debe estar presente. En Debian/Ubuntu: sudo apt install libwebkit2gtk-4.1-dev.
• DEB/AppImage: generados con pnpm instaladorlinux o pnpm instalador:linux.
• Wayland: la app funciona en X11 y Wayland. Si la ventana se ve mal en Wayland, fuerza X11 con GDK_BACKEND=x11.

---

🐞 Diagnóstico general

Comandos útiles para reportar un bug:

node --version           # >= 18
rustc --version          # toolchain estable
cargo --version          # tauri-cli instalado
pnpm --version
pnpm -C apps/desktop tauri --version

Logs:

• Rust: visibles en la terminal donde se ejecutó tauri dev. Persistir con tee desktop-dev.log.
• Frontend: DevTools (Ctrl+Shift+I en dev) → pestaña Console.
• Storage: %LOCALAPPDATA%/ContextCodeDesktop/ (Windows) o ~/.local/share/ContextCodeDesktop/ (Linux/Mac).

Si nada resuelve, abre un issue con:

1. Versión de la app (Help → About).
2. SO + arquitectura.
3. Output de los comandos de diagnóstico.
4. Pasos exactos para reproducir.
5. Logs relevantes (sin secretos).