Dépannage

La plupart des problèmes de Crew ont un correctif qui se résume à une commande shell. Cette page est un guide de tri. Commencez par une vérification de l'état :

kirocrew doctor

doctor rapporte l'état de chaque sous-système : détection du binaire kiro-cli, authentification de l'agent, modèle d'incorporation, jetons Slack, validité de la configuration et sondes de serveur MCP. S'il signale un problème, passez à la section correspondante ci-dessous.

Le répertoire cible de l'installation n'est pas dans votre PATH. Les correctifs dépendent de l'installateur :

• Installateur de roue précompilée — utilise pipx lorsqu'il est disponible, sinon ~/.kiro/crew/venv. Assurez-vous que ~/.local/bin (valeur par défaut de pipx) ou ~/.kiro/crew/venv/bin figure dans PATH.
• pip install -e . — assurez-vous que le répertoire des scripts de votre Python figure dans PATH. Habituellement ~/.local/bin (installation utilisateur) ou le bin/ du venv.
• Docker — appelez via docker exec kirocrew kirocrew ….

Puis source ~/.bashrc (ou redémarrez votre shell).

Sur Windows, utilisez python et py depuis un venv :

py -3.12 -m venv .venv
.venv\Scripts\activate
pip install -e . tzdata
python -m kiro_crew gateway

tzdata est requis — Windows ne fournit aucune base de données de zones IANA, donc zoneinfo.ZoneInfo(...) échoue sans elle.

Le point d'entrée a sondé le bac à sable interne de l'espace de noms utilisateur Linux et cela a échoué sous la politique seccomp/AppArmor de l'environnement d'exécution du conteneur. Deux options :

1. Autoriser les espaces de noms utilisateur — redémarrez avec --security-opt seccomp=<profil autorisant unshare/clone>. La passerelle sonde à nouveau au prochain démarrage et active le bac à sable.
2. Accepter une exécution non isolée — redémarrez avec -e KIROCREW_ALLOW_UNSANDBOXED=1. Les commandes de l'agent s'exécutent sans le bac à sable interne; le conteneur reste la seule limite d'isolation.

La sortie du journal au démarrage indique quelle posture a été choisie.

Le backend de l'agent n'a pas répondu à la prise de contact. Causes courantes :

1. kiro-cli n'est pas installé — la page Set up Kiro du tableau de bord vous guide, ou kirocrew doctor signale un binaire manquant
2. Non connecté — exécutez kiro-cli login
3. Configuration MCP brisée — kirocrew setup --agent-only --clean reconstruit l'agent à partir de zéro
4. Le premier lancement est lent — l'initialisation du serveur MCP peut prendre plus de 60 secondes; patientez

Le processus kiro-cli s'est arrêté brusquement. Crew récupère automatiquement en recréant la session et en réessayant. Si cela se répète :

• Consultez kirocrew logs -f pour l'erreur sous-jacente
• Si le processus a été tué par manque de mémoire (OOM), réduisez les sous-agents concurrents (agent.max_subagents) ou augmentez la mémoire de l'hôte
• Le coupe-circuit se déclenche après 5 échecs consécutifs et se réinitialise automatiquement — récupère habituellement de lui-même

Le répertoire de projet actif n'est pas défini. Vérifiez avec kirocrew config get project_dir, ou définissez-le dans l'en-tête de session du tableau de bord.

Si le CWD est défini mais que l'agent ne peut toujours pas lire un chemin particulier, consultez le bac à sable du SE — certains chemins sont masqués dans les modes auto et strict.

1. Vérifiez l'état du modèle d'incorporation : kirocrew doctor signale si l'environnement d'exécution groupé a téléchargé le modèle
2. Les téléchargements à la première exécution se font en arrière-plan (~610 Mo). Attendez quelques minutes et revérifiez.
3. Définissez une URL miroir si le CDN est inaccessible : export KIROCREW_EMBED_MODEL_URL=<url>
4. Repliez-vous sur Ollama si vous préférez : ollama pull qwen3-embedding:0.6b et vérifiez curl http://localhost:11434/api/tags

Jusqu'à ce que le modèle arrive, la mémoire se replie sur la recherche par mots-clés (LIKE sur le texte + les balises). L'agent continue de fonctionner — simplement sans classement sémantique.

Le memory.db restauré est corrompu. Habituellement un problème de copie (transfert interrompu). Essayez :

kirocrew restore snapshot.tar.gz --mode replace --dry-run    # preview
kirocrew restore snapshot.tar.gz --mode replace --components memory

Si cela échoue toujours, l'instantané lui-même est défectueux. Restaurez à partir d'un instantané plus ancien ou importez manuellement memory.db depuis une autre source.

• Le mode incognito est activé — vérifiez l'indicateur incognito dans l'en-tête de session. Les sessions incognito n'écrivent jamais en mémoire.
• Le consolidateur ne fonctionne pas — la consolidation de la mémoire se déclenche à 30 messages (chemin des préférences) ou après 3 h d'inactivité (chemin de l'historique). Une session courte peut n'atteindre aucun des deux déclencheurs.
• Disque plein — df -h ~/.kiro/crew; SQLite échoue silencieusement à l'écriture lorsque le disque est plein

Slack est optionnel — le tableau de bord fonctionne sans lui. Si vous voulez utiliser Slack :

1. Vérifiez que les jetons sont définis : cat ~/.kiro/crew/.env devrait afficher SLACK_APP_TOKEN=xapp-…, SLACK_BOT_TOKEN=xoxb-…, KIROCREW_OWNER_ID=U0…
2. Confirmez que le mode Socket est activé dans les paramètres de votre application Slack
3. Réexécutez kirocrew setup — l'assistant demande les deux jetons
4. kirocrew doctor signale l'état de la connexion Slack

• Verrou du propriétaire — la passerelle Slack est verrouillée sur KIROCREW_OWNER_ID. Seul votre identifiant de membre Slack peut envoyer un message direct au bot. Les messages non-propriétaires sont abandonnés silencieusement.
• Enterprise Grid — si slack.allowed_enterprise_ids est défini, les messages provenant d'autres espaces de travail sont abandonnés
• Bot hors ligne — consultez kirocrew logs -f pour des erreurs de déconnexion websocket

Vous avez ajouté une nouvelle fonctionnalité qui nécessite une portée non accordée au moment de l'installation. Correctif :

1. Dans les paramètres de l'application Slack, ajoutez la portée manquante sous OAuth & Permissions → Bot Token Scopes
2. Réinstallez l'application dans votre espace de travail (bouton Install to Workspace)
3. Réexécutez kirocrew setup — collez le nouveau jeton de bot

Ajoutez l'événement app_home_opened, activez le Home Tab dans les paramètres de l'application Slack, réinstallez l'application.

Bug connu de l'interface utilisateur de Slack. Utilisez plutôt Features → OAuth & Permissions → Install to Workspace — cela fait la même chose.

1. Confirmez que DISCORD_BOT_TOKEN est défini et que kirocrew doctor signale Discord connecté
2. Vérifiez que l'utilisateur figure dans discord.allowed_users (liste d'autorisation refusant par défaut)

Ajoutez l'identifiant Discord de l'utilisateur à discord.allowed_users via la configuration ou le panneau de paramètres Discord du tableau de bord.

Discord limite les messages à 2000 caractères. Le transport se divise automatiquement. Si vous voyez une troncature au lieu d'une division, vérifiez la présence d'un formateur personnalisé fragile.

1. Vérifiez que ~/.kiro/agents/kirocrew.json contient kirocrew-core et kirocrew-cron
2. Vérifiez que includeMcpJson: false est défini
3. Exécutez kirocrew doctor — il signale l'état des sondes MCP
4. Le panneau Integrations (MCP) du tableau de bord affiche les résultats des sondes en direct

Détruit et reconstruit la configuration MCP à partir de zéro. Résout la plupart des problèmes de « MCP brisé ».

La passerelle déclenche automatiquement une sonde lorsqu'un nouveau serveur apparaît, mais les résultats ne se manifestent qu'au prochain rafraîchissement du tableau de bord. Attendez quelques secondes et rechargez. Si cela reste sur « Unknown », le serveur échoue à la prise de contact — vérifiez le texte de l'erreur ou kirocrew logs -f.

Comportement correct. kirocrew-core et kirocrew-cron sont limités à l'agent et ne devraient pas apparaître dans les sessions kiro-cli interactives. Si c'est le cas, quelque chose les a écrits dans une configuration globale de fournisseur — signalez un bogue.

Vérifiez le badge Crew sur la ligne. S'il reste vert, la règle de préservation copie la configuration du serveur dans ~/.kiro/crew/mcp.json avant de le retirer du global, il continue donc de se charger dans les sessions Crew.

Désactivez le badge Crew avant de retirer du global pour un retrait complet.

La réinitialisation de session vide le bassin préchargé. Utilisez Dashboard → Apply & Restart, ou exécutez kirocrew config set (ce qui déclenche automatiquement un redémarrage).

• Jeton expiré — générez-en un nouveau : kirocrew token --ttl 2h
• Adresse IP modifiée — les jetons du tableau de bord sont épinglés à l'IP dès la première utilisation; si votre IP a changé, générez un nouveau jeton
• Accès distant sans jeton — vous ne pouvez pas accéder au tableau de bord à distance sans un jeton valide; les trois exceptions sont les sondes de santé, les ressources statiques et l'amorçage en boucle locale uniquement

L'environnement d'exécution groupé télécharge son modèle via HTTPS depuis le CDN de Crew au démarrage de la passerelle. Vérifiez :

• L'accessibilité réseau vers le CDN
• L'espace disque dans ~/.kiro/crew/models/
• Définissez KIROCREW_EMBED_MODEL_URL vers un miroir si le CDN par défaut est inaccessible

Jusqu'à ce que le modèle arrive, la mémoire fonctionne avec la recherche par mots-clés.

• Bassin de sessions froid — le premier message d'un nouvel onglet subit une pénalité de démarrage à froid de 3 à 5 secondes. Augmentez session.pool_size (par défaut 1) si vous disposez de RAM disponible.
• Rafale de préchauffage — les conteneurs Docker avec de nombreux serveurs MCP peuvent prendre plus de 60 secondes au premier démarrage

La passerelle est encore en cours d'initialisation. Causes courantes :

• Les serveurs MCP terminent leurs sondes initiales
• Le bassin de sessions préchargé est en train d'être généré
• Le téléchargement du modèle d'incorporation est en cours

Attendez 30 secondes, puis rafraîchissez. Si cela persiste → consultez kirocrew logs -f.

kirocrew doctor              # diagnose
kirocrew gateway --port auto # try a random port if 5476 is in use

Si le port 5476 est utilisé :

lsof -iTCP:5476 -sTCP:LISTEN    # find what's on it

• Coupe-circuit — 5 échecs consécutifs se réinitialisent automatiquement; récupère habituellement de lui-même
• Réinitialisation forcée — depuis le tableau de bord, supprimez l'emplacement et démarrez-en un nouveau
• Tout arrêter — kirocrew restart

Le contexte de session se remplit trop rapidement. Options :

• Réduire le contexte injecté : skills.lazy_load: true pour un budget plus strict
• Augmenter le seuil de compaction : session.autocompact_pct: 95
• Utiliser le mode incognito pour les conversations sensibles à volume élevé

Le chien de garde se déclenche à 60 min (avertissement) et 2 h (réinitialisation). Si la tâche est réellement bloquée :

• Consultez kirocrew logs -f pour l'activité de session de l'étape spécifique
• Annulez et redémarrez à partir d'une étape spécifique : POST /api/taskrunner/{task_id}/retry avec from_step: N

• TEST_TIMEOUT est de 90 min par exécution de test; si votre suite de tests prend plus de temps, remplacez-la par une configuration par étape ou divisez la tâche
• Exécutez les tests manuellement avec kirocrew run TASK.md --no-test pour voir ce que l'agent produit avant la barrière de test

La tâche a réessayé la même étape en échec 3 fois avec des erreurs identiques. L'exécuteur de tâches marque l'étape FAILED pour éviter de gaspiller des tentatives sur un correctif impossible.

Déboguer : vérifiez le message d'erreur de l'étape. Causes courantes :

• Le critère d'acceptation de l'étape est irréalisable compte tenu de la base de code actuelle
• Une dépendance est manquante (l'agent ne peut pas non plus l'installer)
• Le réviseur rejette pour une raison sans rapport avec la justesse

Envisagez de marquer l'étape requires_approval: true et d'inspecter l'état manuellement.

Consultez spawn list pour l'état. S'il affiche stalled (aucune activité depuis 120 s), le sous-agent est inactif — soit légitimement (en attente d'approbation), soit bloqué.

• Bloqué en attente d'approbation — vérifiez le tableau de bord pour une invite d'approbation en attente
• Bloqué — utilisez spawn cancel <id> depuis le bouton Stop de la ligne du tableau de bord

Le récupérateur force la récupération au délai d'expiration strict de 30 minutes.

Le sous-agent peut avoir échoué au démarrage (tâche vide, mémoire faible, cwd rejeté, refus de gouvernance). Consultez spawn list pour un état terminal failed avec la raison.

• La passerelle était hors service — le planificateur ne rattrape pas le retard au redémarrage
• La tâche est en pause — kirocrew cron list affiche l'état
• --no-crons a été passé à gateway — le planificateur est désactivé

Vérifiez l'acheminement de la livraison :

• Par défaut : message direct Slack si configuré, sinon notification du tableau de bord
• Avec le marqueur <!-- deliver:C0123CHANNEL --> : acheminé vers ce canal Slack
• Avec --silent : aucune notification à moins que l'agent n'en envoie une explicitement

• kirocrew config set — déclenche automatiquement un redémarrage du bassin de sessions. Devrait fonctionner.
• Changement de variable d'environnement — nécessite kirocrew restart
• Modification manuelle de fichier — vous pouvez aussi exécuter kirocrew restart pour forcer un rechargement

Vous avez défini une valeur de configuration numérique hors de la plage autorisée. Elle a été plafonnée à la limite; l'entrée SEL enregistre le plafonnement. Ajustez votre valeur ou consultez la référence Configuration pour connaître les plages valides.

Le point de contrôle WAL a échoué parce que la passerelle détient un verrou. L'instantané se poursuit tout de même — l'API backup() de SQLite produit une copie cohérente incluant les données WAL validées. L'avertissement est informatif.

Les instantanés rejettent les liens symboliques et les liens physiques pour des raisons de sécurité. Si votre instantané en contient un (inhabituel), l'archive est mal formée. Régénérez l'instantané à partir d'une source propre.

Définissez instances.enabled: true dans ~/.kiro/crew/config.json et redémarrez la passerelle.

L'assouplissement du CSP frame-src ne s'applique qu'aux ports de tunnel actifs. Confirmez que l'instance est connectée (le panneau Manage affiche un badge connecté vert), pas seulement ajoutée.

Renouvelez les identifiants SSH (rajoutez la clé à ssh-agent). Les tunnels se réparent d'eux-mêmes une fois SSH restauré.

La sonde de santé + l'auto-réparation à deux niveaux réessaient pendant environ 2 min (8 tentatives, avec un plafond de recul exponentiel). Si elle abandonne, un diagnostic s'exécute automatiquement. Vérifiez :

• Que la passerelle distante fonctionne réellement (ssh <host> kirocrew doctor)
• La stabilité SSH du concentrateur vers le distant
• La dérive temporelle — les jetons sont signés dans le temps; un grand décalage d'horloge cause un rejet

Accordez l'autorisation d'utiliser le microphone du navigateur pour l'origine du tableau de bord. Dans Chrome : cadenas de la barre d'adresse → Site settings → Microphone → Allow.

• Vérifiez l'autorisation audio de l'onglet du tableau de bord (cadenas du navigateur)
• Confirmez que la sortie du système n'est pas coupée
• Le téléchargement de la voix Piper à la première utilisation peut ne pas être terminé; vérifiez le réseau + ~/.kiro/crew/voices/

• Essayez une pièce plus silencieuse
• Passez à aws_transcribe pour une précision de niveau infonuagique : pip install "kirocrew[voice]", puis définissez voice.stt_provider: "aws_transcribe" et configurez les identifiants AWS

La pile de récupération est manquante pour ce profil / cette région. Deux options :

• Exécutez install-reaper.sh --profile <name> --region <region>
• Utilisez ttl_hours: 0 (persistant, aucun récupérateur nécessaire)

Les en-têtes du site déployé datent d'avant la pile de base actuelle. Tout déploiement subséquent met à jour la pile en place. En attendant, la carte affiche le statut de repli avec un lien simple — cliquez pour voir le site.

Si rien ici ne correspond à votre problème :

• Journaux détaillés — kirocrew logs -f (suivi en direct), kirocrew doctor --verbose
• Signaler un bogue — github.com/kirodotdev/KiroCrew/issues
• Consulter la source — chaque sous-système est documenté sous docs/system-specs/modules/ dans le dépôt Crew