L’erreur « Claude Code process exited with code 1 » surgit souvent quand tu exécutes le Claude Code SDK dans le terminal de debug de VSCode. Elle apparaît au pire moment, au milieu d’un flux TypeScript ou Node.js, puis elle bloque net les queries vers Claude. Les issues GitHub d’Anthropic la documentent depuis juillet 2025, avec un stack trace peu disert qui renvoie vers sdk.mjs ligne 224. L’article explique l’origine du crash et donne des correctifs immédiats, du plus simple au plus robuste.
Qu'est-ce que l'erreur "Claude Code process exited with code 1" ?
L’erreur signifie que le sous-processus lancé par Claude Code se termine avec un code de sortie 1, donc un échec d’exécution côté système. Elle se déclenche souvent quand ton code appelle query() et que le SDK tente de démarrer la brique CLI en arrière-plan. Le message frustre car il ne décrit pas la cause racine et renvoie vers une trace générique. Le résultat reste concret : aucune réponse IA ne remonte pendant une session de debug.
- L’appel concerné : query().
- Le package concerné : @anthropic-ai/claude-code.
- Le contexte récurrent : terminal de debug VSCode (mode debug TypeScript/Node).
- L’environnement typique : devcontainer mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm sur Debian 12.
- La trace fréquente : ChildProcess.
dans sdk.mjs:224 , avec Claude CLI 1.0.61.
Causes principales de cette erreur
Interférence du debugger VSCode
VSCode auto-attach injecte des variables d’environnement de debug, dont NODE_OPTIONS et VSCODE_INSPECTOR_OPTIONS (avec un –require vers un bootloader) et VSCODE_INSPECTOR_OPTIONS (avec la configuration inspectorIpc). Le SDK lance ensuite un sous-processus Claude qui hérite de ces variables, puis le debugger interfère avec ce sous-processus et provoque l’arrêt.
Le processus principal que tu débugges continue souvent à tourner sans anomalie. Le crash touche surtout le sous-processus Claude, ce qui donne l’illusion d’un problème de SDK alors que l’environnement de debug déclenche l’échec.
Conditions de service non acceptées
L’erreur apparaît aussi quand les derniers terms of service ne sont pas acceptés, car l’exécution CLI échoue avant de finaliser l’authentification et le SDK récupère un exit code 1. Le piège vient du terminal de debug VSCode, qui masque ou perturbe parfois l’étape interactive d’acceptation. Un terminal externe règle le point de friction, un cas remonté dans l’issue GitHub #8557.
- Accepter les terms of service en lançant Claude dans un terminal séparé de VSCode.
- Utiliser l’issue GitHub #8557 comme repère de diagnostic.
- Vérifier que l’acceptation débloque bien les queries.
Version Node.js incompatible
Un schéma se répète dans les retours utilisateurs : une version Node trop récente (Node 24 ou 25) entraîne un crash discret du sous-processus, puis le SDK renvoie « process exited with code 1 ». Un retour vers Node 22 stabilise l’exécution dans de nombreux environnements, dont des devcontainers. La variable DEBUG=1 aide aussi à rendre l’échec plus bavard côté sous-processus.
| Version Node | Comportement observé (selon issues) |
|---|---|
| Node 24/25 | Crash silencieux ou exit code 1 sur le sous-processus Claude. |
| Node 22 | Exécution stable, queries qui aboutissent. |
| DEBUG=1 (pour diagnostiquer) | Logs plus détaillés, erreurs visibles sur stderr du sous-processus. |
Solutions pour résoudre l'erreur
Nettoyer les variables d'environnement
La voie la plus propre consiste à isoler l’environnement du sous-processus Claude du contexte de debug VSCode. Tu gardes le debugger sur ton process Node principal, mais tu retires les variables qui déclenchent l’attachement parasite sur le process enfant. Cette approche vise un résultat net : plus de crash du CLI, donc des queries qui repartent.
- Créer une copie d’environnement : const cleanEnv = { …process.env };.
- Supprimer NODE_OPTIONS dans cleanEnv.
- Supprimer VSCODE_INSPECTOR_OPTIONS dans cleanEnv.
- Passer options: { cwd, permissionMode, env } avec le bloc ci-dessous.
import { query } from "@anthropic-ai/claude-code";
const cleanEnv = { …process.env };
delete cleanEnv.NODE_OPTIONS;
delete cleanEnv.VSCODE_INSPECTOR_OPTIONS;
const result = await query("Hello", {
options: {
cwd: "/dir",
permissionMode: "bypassPermissions",
env: cleanEnv,
},
});
console.log(result);
Ce nettoyage stoppe la contamination du sous-processus par les paramètres du debugger et restaure l’exécution. Un correctif de ce type a été intégré dans des agents via un commit attribué à Sanchay-T en novembre 2025.
Accepter les terms of service et reset
Cette procédure sert de check rapide côté authentification et terms of service.
- Lancer claude dans un terminal séparé de VSCode et accepter les terms of service.
- Exécuter /logout.
- Relancer claude pour forcer une nouvelle authentification.
- Supprimer ~/.config/claude-code/auth.json pour réinitialiser l’auth.
Autres correctifs rapides
Ces actions donnent des quick wins à tester dans l’ordre, en gardant un biais pour le diagnostic simple avant les changements d’environnement. Elles couvrent les causes usuelles : clé absente, session incohérente, hooks instables, logs insuffisants, configuration corrompue, version Node inadaptée.
- Vérifier la présence de ANTHROPIC_API_KEY.
- Redémarrer la session avec /clear ou exit puis relancer claude.
- Lancer claude –no-hooks à titre temporaire.
- Activer DEBUG=1 pour obtenir des logs détaillés sur stderr.
- Exécuter claude config –reset si la configuration paraît corrompue.
- Revenir à Node 22 si tu utilises Node 24 ou 25.
