Résolution des problèmes

Cette page rassemble les problèmes les plus courants lors de l'utilisation d'Almirant et leurs solutions. Si votre problème n'apparaît pas ici, contactez le support à [email protected].

Problèmes fréquents

Problème	Cause	Solution
L'IDE ne se connecte pas à MCP	URL ou API key incorrecte	Vérifiez que l'URL est https://api.almirant.ai/mcp?projectId=<id> et que l'API key est valide. Vérifiez que le backend est en cours d'exécution si vous utilisez localhost.
« Unauthorized » lors de la connexion MCP	API key expirée ou révoquée	Générez une nouvelle API key dans Configuration > API Keys et mettez à jour la configuration de votre IDE.
MCP se connecte mais ne voit pas mes projets	projectId absent ou incorrect	Vérifiez le projectId dans l'URL. Vous pouvez l'obtenir depuis l'URL du navigateur en ouvrant le projet dans Almirant, ou en utilisant list_projects sans projectId.
Je ne peux pas me connecter	Compte Google non autorisé	Votre e-mail doit figurer dans la liste des e-mails autorisés de l'organisation. Contactez l'administrateur pour qu'il l'ajoute.
Les Work Items n'apparaissent pas dans le board	Éléments archivés ou filtre actif	Vérifiez les filtres actifs dans la barre supérieure du board. Si les éléments sont archivés, activez le filtre « Afficher les archivés » pour les voir.
L'IA n'implémente pas la tâche	Work Item sans description suffisante	Assurez-vous que le Work Item a une description détaillée avec des critères d'acceptation. Sans contexte, l'IA ne peut pas déterminer quoi implémenter.
Le glisser-déposer ne fonctionne pas dans le board	Conflit avec une extension du navigateur	Désactivez les extensions qui modifient le DOM (bloqueurs de publicité agressifs, outils d'accessibilité qui interceptent les événements). Essayez dans une fenêtre de navigation privée.
Le webhook ne reçoit pas d'événements	URL inaccessible ou HTTPS requis	Vérifiez que l'URL est accessible depuis Internet et utilise HTTPS. Consultez le journal des livraisons dans Configuration > Webhooks pour voir les erreurs.
Le webhook retourne 401	Signature non vérifiée correctement	Assurez-vous d'utiliser le body brut (raw) pour calculer la signature HMAC, et non le body analysé. Vérifiez que le secret correspond à celui configuré.
Le sprint ne se ferme pas	Des Work Items ne sont pas résolus	Les sprints peuvent être fermés avec des éléments en attente. Les éléments non terminés peuvent être déplacés vers le backlog ou le sprint suivant à la fermeture.
Erreur lors de l'import de leads (CSV)	Format de fichier incorrect	Vérifiez que le CSV utilise des virgules comme séparateurs et contient les colonnes requises (name, email). Téléchargez le modèle depuis l'écran d'import.
Le Feedback Widget n'apparaît pas	Script non chargé ou key incorrecte	Vérifiez que le script est placé avant </body>, que l'URL est correcte (https://cdn.almirant.ai/feedback-widget.iife.js) et que la publicKey est valide.
Erreur « CORS » lors de la connexion depuis l'IDE	Le backend ne configure pas CORS pour votre origine	Si vous utilisez le backend local, vérifiez que CORS_ORIGIN dans votre .env contient la bonne origine. En production, cela ne devrait pas se produire.
La planification IA ne génère aucun résultat	Fournisseur IA non configuré	Accédez à Configuration > Intégrations et connectez un fournisseur IA (Anthropic ou OpenAI). Vous avez besoin d'au moins une API key active.
Performances lentes lors du chargement de grands boards	Trop d'éléments visibles	Utilisez des filtres pour limiter les éléments visibles. Archivez les anciens éléments terminés. Les boards fonctionnent mieux avec moins de 200 éléments visibles.

Dépannage avancé

Vérifier la connexion MCP

Exécutez cette commande dans Claude Code pour vérifier que la connexion fonctionne :

Utilise l'outil list_projects pour lister mes projets

Si vous voyez vos projets, la connexion est correcte. Sinon :

1. Vérifiez que le backend est en cours d'exécution (bun run dev:api en développement local)
2. Vérifiez l'URL dans .mcp.json ou .claude/settings.json
3. Vérifiez que l'API key dispose des autorisations pour le projet indiqué
4. Consultez les logs du backend pour trouver des erreurs d'authentification

Vérifier les webhooks

Pour dépanner un webhook qui ne fonctionne pas :

1. Accédez à Configuration > Webhooks et sélectionnez le webhook
2. Consultez l'onglet Livraisons pour voir les tentatives récentes
3. Cliquez sur une livraison en échec pour en voir le détail (request, response, headers)
4. S'il n'y a aucune livraison, vérifiez que les événements souscrits correspondent à l'action que vous effectuez
5. Utilisez un service tel que webhook.site pour vérifier qu'Almirant envoie correctement les requêtes

Problèmes avec le Feedback Widget

Si le widget n'apparaît pas ou ne fonctionne pas :

1. Ouvrez la console du navigateur (F12 > Console) et recherchez des erreurs
2. Vérifiez que le script s'est correctement chargé : saisissez FeedbackWidget dans la console. S'il renvoie undefined, le script ne s'est pas chargé
3. Vérifiez que FeedbackWidget.isReady() renvoie true
4. Vérifiez que la publicKey est correcte dans la configuration du projet
5. Si vous utilisez React, assurez-vous que le composant <FeedbackWidget> est monté dans l'arbre

Logs du navigateur

Pour tout problème avec l'interface web :

1. Ouvrez les DevTools (F12)
2. Accédez à l'onglet Console et recherchez les erreurs en rouge
3. Accédez à l'onglet Network et filtrez les requêtes en échec (statut 4xx ou 5xx)
4. Si vous signalez un bug, incluez :
   • Une capture des erreurs de console
   • L'URL de la page où il se produit
   • Le navigateur et sa version
   • Les étapes pour le reproduire

Conseil

Si quelque chose ne fonctionne pas comme prévu, commencez toujours par vérifier la console du navigateur et les logs du backend. La plupart des problèmes se résolvent avec les informations de ces deux emplacements.