Solucion de problemas

Esta pagina recopila los problemas mas comunes al usar Almirant y sus soluciones. Si tu problema no aparece aqui, contacta con soporte en [email protected].

Problemas frecuentes

Problema	Causa	Solucion
El IDE no conecta con MCP	URL o API key incorrecta	Verifica que la URL sea https://api.almirant.ai/mcp?projectId=<id> y que la API key sea valida. Comprueba que el backend este corriendo si usas localhost.
"Unauthorized" al conectar MCP	API key expirada o revocada	Genera una nueva API key en Configuracion > API Keys y actualiza la configuracion de tu IDE.
MCP conecta pero no ve mis proyectos	Falta projectId o es incorrecto	Verifica el projectId en la URL. Puedes obtenerlo desde la URL del navegador al abrir el proyecto en Almirant, o usando list_projects sin projectId.
No puedo hacer login	Cuenta de Google no autorizada	Tu email debe estar en la lista de emails permitidos de la organizacion. Contacta al administrador para que lo agregue.
Work items no aparecen en el board	Items archivados o filtro activo	Revisa los filtros activos en la barra superior del board. Si los items estan archivados, activa el filtro "Mostrar archivados" para verlos.
La IA no implementa la tarea	Work item sin descripcion suficiente	Asegurate de que el work item tenga una descripcion detallada con criterios de aceptacion. Sin contexto, la IA no puede determinar que implementar.
Drag and drop no funciona en el board	Conflicto con extension del navegador	Desactiva extensiones que modifiquen el DOM (ad blockers agresivos, herramientas de accesibilidad que interceptan eventos). Prueba en una ventana de incognito.
Webhook no recibe eventos	URL no accesible o HTTPS requerido	Verifica que la URL sea accesible desde internet y use HTTPS. Revisa el log de entregas en Configuracion > Webhooks para ver los errores.
Webhook devuelve 401	Firma no verificada correctamente	Asegurate de usar el body crudo (raw) para calcular la firma HMAC, no el body parseado. Verifica que el secret coincida con el configurado.
El sprint no se cierra	Hay work items sin resolver	Los sprints pueden cerrarse con items pendientes. Los items no completados se pueden mover al backlog o al siguiente sprint al cerrar.
Error al importar leads (CSV)	Formato de archivo incorrecto	Verifica que el CSV use comas como separador y tenga las columnas requeridas (name, email). Descarga la plantilla desde la pantalla de importacion.
Feedback widget no aparece	Script no cargado o clave incorrecta	Verifica que el script este antes de </body>, que la URL sea correcta (https://cdn.almirant.ai/feedback-widget.iife.js) y que la publicKey sea valida.
Error "CORS" al conectar desde el IDE	Backend no configura CORS para tu origen	Si usas el backend local, verifica que CORS_ORIGIN en tu .env incluya el origen correcto. En produccion, esto no deberia ocurrir.
La planificacion AI no genera resultados	Proveedor de IA no configurado	Ve a Configuracion > Integraciones y conecta un proveedor de IA (Anthropic u OpenAI). Necesitas al menos una API key activa.
Slow performance al cargar boards grandes	Demasiados items visibles	Usa filtros para limitar los items visibles. Archiva items completados antiguos. Los boards funcionan mejor con menos de 200 items visibles.

Depuracion avanzada

Verificar la conexion MCP

Ejecuta este comando en Claude Code para verificar que la conexion funciona:

Usa la herramienta list_projects para listar mis proyectos

Si ves tus proyectos, la conexion es correcta. Si no:

1. Verifica que el backend este corriendo (bun run dev:api en desarrollo local)
2. Comprueba la URL en .mcp.json o .claude/settings.json
3. Verifica que la API key tenga permisos para el proyecto indicado
4. Revisa los logs del backend para ver errores de autenticacion

Verificar webhooks

Para depurar un webhook que no funciona:

1. Ve a Configuracion > Webhooks y selecciona el webhook
2. Revisa la pestana Entregas para ver intentos recientes
3. Haz clic en una entrega fallida para ver el detalle (request, response, headers)
4. Si no hay entregas, verifica que los eventos suscritos coincidan con la accion que estas realizando
5. Usa un servicio como webhook.site para probar que Almirant envia las peticiones correctamente

Problemas con el Feedback Widget

Si el widget no aparece o no funciona:

1. Abre la consola del navegador (F12 > Console) y busca errores
2. Verifica que el script se cargo correctamente: escribe FeedbackWidget en la consola. Si es undefined, el script no cargo
3. Verifica que FeedbackWidget.isReady() devuelve true
4. Comprueba que la publicKey es correcta en la configuracion del proyecto
5. Si usas React, asegurate de que el componente <FeedbackWidget> esta montado en el arbol

Logs del navegador

Para cualquier problema con la interfaz web:

1. Abre DevTools (F12)
2. Ve a la pestana Console y busca errores en rojo
3. Ve a la pestana Network y filtra por peticiones fallidas (status 4xx o 5xx)
4. Si reportas un bug, incluye:
   • Captura de los errores de consola
   • URL de la pagina donde ocurre
   • Navegador y version
   • Pasos para reproducir

Consejo

Si algo no funciona como esperas, el primer paso siempre es revisar la consola del navegador y los logs del backend. La mayoria de los problemas se resuelven con informacion de estos dos lugares.