FAQ et dépannage

Chaque réponse ci-dessous a été rencontrée par quelqu’un de la flotte. Si votre problème n’y est pas, consultez d’abord les documents de référence kaboum (04 API, 05 configuration, 08 opérations).

Quelle version de Copier me faut-il ?

9.4.0 ou plus récent. copier.yml épingle _min_copier_version: "9.4.0" — la plus ancienne version réellement testée par la CI. La ligne « 9.0.0+ » du tableau du README est périmée : la 9.0.0 était revendiquée mais jamais exercée, et elle ne s’installe pas sur Python 3.12.

pip install "copier>=9.4.0"   # or: pipx install copier / uv tool install copier

Pourquoi mon rendu inclut-il des éditions du template non commitées ?

Parce qu’un checkout de template sale est rendu. Quand vous générez depuis un checkout kaboum local avec des changements non commités, copier les inclut automatiquement (DirtyLocalWarning: Dirty template changes included automatically) — même avec --vcs-ref défini. Le rendu passe, mais il ne prouve rien sur ce que produit un checkout propre : la CI, les autres kreators et copier update ne voient jamais que ce qui est commité.

Commitez avant de vérifier. Traitez l’avertissement de checkout sale comme le signal que votre rendu vert a prouvé moins que vous ne le pensez.

Pourquoi mon rendu tout neuf manque-t-il des derniers changements du template ?

Copier utilise par défaut le dernier tag git, pas HEAD. Un simple copier copy . ../my-actor depuis un checkout kaboum rend ce qu’était la dernière version. Pour tester l’état courant du template :

copier copy . ../my-actor --vcs-ref=HEAD --data project_name=myactor --defaults

Ou rendez une version précise : --vcs-ref=v1.7.2. Générez aussi, en usage réel, depuis un référentiel git, pas un chemin local — .copier-answers.yml enregistre alors _commit et copier update fonctionne ensuite.

Que sont les fichiers `.rej` laissés par `copier update` ?

Des conflits de mise à jour. Copier a trouvé un fichier que vous aviez personnalisé (un point d’extension comme src/agent/agent.py ou orchestrator.py) dont le template avait aussi changé, et il n’a pas pu les fusionner. Pour chaque .rej :

Ouvrez le hunk rejeté et le fichier cible côte à côte.
Réappliquez votre personnalisation à la main sur la nouvelle version du template — ou adoptez consciemment la version du template et reportez votre changement.
Supprimez le fichier .rej une fois résolu.

Ne laissez jamais de fichiers .rej dans un commit — la CI et les équipes de revue y voient une mise à jour inachevée. Attendez-vous à des conflits exactement là où vous avez personnalisé des fichiers possédés par le template ; orchestrator.py est un point d’extension documenté et fera conflit à chaque mise à jour, quoi qu’il arrive.

Pourquoi `make kaoohi-config-check` a-t-il échoué ?

src/kaoohi/config.json est dérivé, jamais édité à la main — émis depuis vos champs Pydantic Settings plus [tool.kaoohi] dans pyproject.toml. La vérification échoue quand le fichier commité ne correspond plus à ce que l’émetteur produirait (périmé après une édition de config.py, un changement de pyproject, ou une édition manuelle partielle).

Correctif : régénérez et commitez le fichier dérivé.

make kaoohi-config          # emit + freshness check
git add src/kaoohi/config.json

La même validation tourne au build d’image — une configuration mal formée fait échouer le build Docker : corrigez donc localement d’abord.

Une règle d’accord (A–G) a fait échouer ma vérification de configuration — que signifient-elles ?

L’émetteur valide config.json contre src/kaoohi/schema.json plus sept règles d’accord :

Règle	Signification
A	Un élément requis géré par l’utilisateur ne peut pas être masqué.
B	Un élément visible géré par la plateforme doit porter un `creator_value`.
C	`fed_by_connector` doit référencer un connecteur déclaré (p. ex. `integration_type=n8n` déclare `n8n` pour vous).
D	Le type d’un `creator_value` doit correspondre au `type` de l’élément.
E	Les éléments booléens rejettent la validation `min`/`max`/`pattern`/`length`/`enum`.
F	`creator_value` et `fed_by_connector` sont mutuellement exclusifs.
G	Un paramètre `type='secret'` ne doit jamais porter de valeur.

Le message d’erreur nomme l’élément et la règle — corrigez l’annotation dans config.py (ou [tool.kaoohi]), jamais le JSON émis.

Pourquoi `test_contract.py` (topic-contract) échoue-t-il ?

Le test topic-contract embarqué exporte l’OpenAPI de votre acteur et vérifie la surface requise par kaoohi. Un échec dur signifie qu’un endpoint requis (/agent/invoke, /health, /ready, /metrics) manque — généralement parce qu’un import de routeur ou le câblage de create_app() a cassé, ou parce que tests/topic-contract.schema.json (embarqué par le template) a été supprimé. Les endpoints recommandés manquants ne font qu’avertir. Restaurez le schéma embarqué avec copier update, et revérifiez le montage des routeurs dans src/main.py.

Pourquoi `test_system_prompt.py` échoue-t-il après que j’ai édité le prompt ?

Parce qu’il est conçu pour. Les phrases épinglées dans tests/test_system_prompt.py verrouillent les parties du prompt système qui ne doivent pas dériver (identité, frontières, ton). Si vous avez changé le prompt volontairement, mettez à jour les phrases épinglées dans le test — délibérément. N’éditez jamais les sections de prompt possédées par le template pour faire passer un test ; mettez votre personnalisation dans la section ROLE_PLAYBOOK à la place.

Pourquoi `test_capability_boundary.py` échoue-t-il avec FORBIDDEN_VERBS ?

Le test est livré avec FORBIDDEN_VERBS: tuple[str, ...] = () et refuse de passer tant que c’est vide. Remplissez-le avec les verbes que votre acteur ne doit pas porter (p. ex. ("send", "sign", "pay", "bind") si ces actions reviennent à un humain). Vide signifie « aucune frontière déclarée », une décision produit que le template refuse de prendre à votre place — modifiez-le exprès, pas en passant.

Pourquoi le build Docker échoue-t-il autour de la version / SETUPTOOLS_SCM ?

La version vient des tags git via hatch-vcs, et les builds Docker ne peuvent pas lire .git/. Si le build ne peut pas dériver une version, passez-la explicitement — le Dockerfile du template câble déjà l’argument :

docker build --build-arg BUILD_VERSION=v1.2.3 -t ghcr.io/allcare/myactor:v1.2.3 .

Les builds sans tag retombent sur une version dev (0.0.1.devN+g<sha>). Pour publier, étiquetez le dépôt (git tag v1.2.3 && git push --tags) et reconstruisez — /health, /ready et /api/actor/metadata rapportent tous la version.

L’acteur ne démarre pas : connexion PostgreSQL refusée

PostgreSQL est le seul service critique — le démarrage échoue sans lui, par conception (conversations, messages et statistiques y vivent). Vérifiez les réglages de connexion (variables d’environnement host/port/db/user) et que PG est réellement levé (docker compose up -d postgres ou votre provision de plateforme). Une fois le processus levé, /health continue de renvoyer 200 avec status: degraded si Postgres tombe, pour que les redémarrages Kubernetes soient contrôlés plutôt qu’une boucle de crash.

Redis ou une intégration échoue mais l’acteur tourne toujours — pourquoi ?

Par conception. Les services non critiques — Redis (cache d’auth, file de réponses), la couche d’authentification, le client de domaine, les serveurs MCP — journalisent un avertissement et continuent de servir. Seul PostgreSQL a le droit d’empêcher le démarrage. Un avertissement dans les logs n’est donc pas un défaut ; il vous dit quelle capacité optionnelle est dégradée.

Pourquoi mon serveur MCP ne se charge-t-il pas ?

MCP_SERVERS_JSON doit être du JSON valide mappant chaque serveur vers un objet avec transport, url, et headers optionnel :

{"my-server": {"transport": "streamable_http", "url": "http://mcp:3000/mcp", "headers": {}}}

Au démarrage, main.py construit un MultiServerMCPClient (langchain-mcp-adapters) depuis cette variable d’environnement et fusionne les outils avec vos outils de domaine. Une coquille dans le JSON ou la mauvaise clé de transport ne donne silencieusement aucun outil — vérifiez les logs de démarrage pour la section MCP, et validez le JSON avant de déployer.

Pourquoi mon `domain_module` a-t-il été rejeté comme réservé ?

Le validateur refuse mesh, agent, api, core, kaoohi, shared, integrations, middleware, models, storage — des modules que le template lui-même rend sous src/. Un paquet de domaine portant l’un de ces noms masquerait le code possédé par le template ; mesh en particulier faisait que {{domain_module}}_tools.py.jinja et les outils mesh se rendaient vers le même src/agent/tools/mesh_tools.py, ce qui tuait les rendus non interactifs. Choisissez un autre nom (booking, email, pipeline, …).

Le job du scheduler refuse de démarrer (JOB_IMPLEMENTED) — pourquoi ?

Vous avez répondu include_scheduler=true mais laissé le job stub en place. Le template refuse délibérément de démarrer un job non implémenté plutôt que de faire tourner un no-op sur un horaire. Implémentez le job dans src/{domain_module}/jobs.py (en remplaçant le marqueur JOB_IMPLEMENTED), ou désactivez le scheduler. À noter : integration_type=n8n implique le scheduler pour la synchronisation des workflows, indépendamment de cette réponse.

Pourquoi personne ne peut-il acheter mon acteur payant ?

Vous pouvez définir la tarification maintenant (free / one_time / subscription + prix) pour que la fiche soit prête — voir ](fr/feature-status/) pour ce qui est en ligne.

Où est mon paiement ?

Pourquoi Kaoohi ne peut-il pas tirer mon image à l’enregistrement ?

L’assistant d’enregistrement lit config.json directement dans votre image via l’API OCI Distribution (chemin par défaut /app/src/kaoohi/config.json) : le registre doit donc pouvoir servir le pull :

L’image GHCR doit être lisible publiquement (ou autrement joignable par la plateforme) — une image privée fait échouer l’extraction.
L’étiquette doit exister — vérifiez que vous avez poussé la référence exacte saisie (ghcr.io/allcare/myactor:v1.2.3, pas seulement latest).
L’image doit être construite avec le template kaboum pour que la configuration soit cuite au chemin attendu. Si l’extraction échoue avec « Was the image built with the kaboum template? », reconstruisez via le Dockerfile du template et repoussez.

Sources : pack de faits kaboum (§1–§6, §12–§13) et pièges signalés dans le CLAUDE.md / README.md kaboum, vérifiés le 2026-10-13.