Dépannage
Les erreurs les plus fréquentes, traduites en français, avec la marche à suivre pour s'en sortir seul.
Une erreur n'est pas un échec, c'est une information
Tous les messages de cette page ont été rencontrés pour de vrai. Aucun ne signifie « vous n'êtes pas fait pour ça » : chacun indique quoi regarder. Le bon réflexe est toujours le même.
- Lire le message d'erreur en entier, du premier mot à la dernière ligne.
- Reproduire l'erreur : quel clic, quelle commande, quel fichier.
- Chercher dans cette page le mot qui ressemble le plus au message.
- Corriger UNE chose à la fois, puis retester.
Effacer un fichier, réinstaller tout, ou renommer une configuration « pour voir » fait souvent disparaître le message… et crée un problème plus difficile à comprendre. Une erreur lisible vaut mieux qu'un silence.
Chercher dans les pannes
401 Unauthorized — Invalid API key
Ce que ça veut dire La clé d'API est absente, mal collée, ou révoquée.
Correction Refaire /connect en recollant la clé (elle commence par sk- et ne s'affiche qu'une fois). Vérifier qu'aucun espace ne s'est glissé au début ou à la fin.
Pour éviter la prochaine fois Coller la clé immédiatement après sa création, et la stocker dans le gestionnaire de mots de passe du compte, pas dans un fichier du projet.
Insufficient Balance — 402
Ce que ça veut dire Le crédit du compte est épuisé : le modèle ne répond plus.
Correction Recharger le compte (quelques euros suffisent largement), puis vérifier la consommation des dernières sessions.
Pour éviter la prochaine fois Surveiller le coût d'une session de temps en temps, compacter les longues sessions, et préférer les heures creuses.
L'agent ne trouve pas les fichiers du projet
Ce que ça veut dire Le terminal n'est pas ouvert dans le dossier du projet.
Correction Quitter OpenCode (ou ouvrir un nouveau terminal), se placer dans le bon dossier, relancer la commande.
Pour éviter la prochaine fois Vérifier le dossier AVANT la première demande : c'est le réflexe le plus rentable.
L'agent répète les mêmes corrections sans succès
Ce que ça veut dire Le contexte est trop long ou la demande trop large : il tourne en rond.
Correction Compacter la session (/compact), ou en démarrer une neuve (/new) avec une demande plus petite et un critère de réussite précis.
Pour éviter la prochaine fois Une intention par message, un test après chaque modification, et une session neuve par grande étape du projet.
« Je ne vois pas de fichier de ce nom »
Ce que ça veut dire L'agent n'a pas lu ce fichier : il ne connaît que ce qu'on lui montre.
Correction Joindre le fichier dans le message avec @, ou demander à l'agent de le lire.
Pour éviter la prochaine fois Citer les chemins dans la demande : « la page src/pages/index.astro ».
La session a coûté beaucoup plus que prévu
Ce que ça veut dire Le contexte relu à chaque tour a grossi, et la réflexion est facturée en sortie.
Correction Compacter, repartir d'une session neuve, et réserver le mode réflexion aux problèmes difficiles.
Pour éviter la prochaine fois Suivre le coût en direct, ne pas laisser une session ouverte des heures, et poser des questions précises.
fatal: not a git repository
Ce que ça veut dire Le dossier courant n'est pas un dépôt Git — soit pas de git init, soit mauvais dossier.
Correction Vérifier le dossier, puis lancer git init s'il n'a jamais été initialisé.
Pour éviter la prochaine fois Lancer git init en tout début de projet, et vérifier avec git status.
Support for password authentication was removed
Ce que ça veut dire GitHub n'accepte plus le mot de passe du compte en ligne de commande.
Correction Configurer une clé SSH (ssh-keygen puis ajout de la clé publique sur GitHub) ou utiliser gh auth login.
Pour éviter la prochaine fois Faire cette configuration une fois, au début du projet, et la noter dans le README.
Updates were rejected… non-fast-forward
Ce que ça veut dire Les historiques ont divergé : le dépôt GitHub contient des commits que vous n'avez pas.
Correction Récupérer d'abord (git pull --rebase), résoudre les conflits éventuels, puis pousser. Si l'historique distant est vide ou faux, le cas classique est un README créé en cochant une case à la création du dépôt.
Pour éviter la prochaine fois Créer le dépôt GitHub VIDE (aucune case cochée) quand le projet local existe déjà.
« Mes fichiers n'apparaissent pas sur GitHub »
Ce que ça veut dire Les commits existent en local mais n'ont pas été poussés, ou vers un autre dépôt.
Correction git push, puis vérifier l'adresse du dépôt distant avec git remote -v.
Pour éviter la prochaine fois Terminer chaque séance par git push, et vérifier la page GitHub une fois par jour.
« J'ai poussé mon fichier .env par erreur »
Ce que ça veut dire Le secret est public et restera lisible dans l'historique.
Correction Tourner la clé immédiatement (révoquer puis recréer), retirer le fichier du suivi, écrire le .gitignore, puis nettoyer l'historique si nécessaire.
Pour éviter la prochaine fois Écrire le .gitignore avant le premier commit, et vérifier avec git check-ignore .env.
Build failed / « Output directory dist not found »
Ce que ça veut dire La compilation en ligne a échoué, ou le dossier de sortie déclaré n'existe pas.
Correction Ouvrir le journal du build, remonter à la PREMIÈRE erreur, puis la reproduire en local avec npm run build. Vérifier la commande de build et le dossier de sortie (dist).
Pour éviter la prochaine fois Toujours lancer npm run build soi-même avant de pousser ; déclarer NODE_VERSION=22 pour coller à la machine locale.
Le domaine personnalisé reste en « pending »
Ce que ça veut dire Le domaine est rattaché mais l'enregistrement DNS n'existe pas encore.
Correction Créer soi-même un enregistrement CNAME du domaine vers projet.pages.dev, en mode proxied. Le certificat HTTPS est ensuite émis automatiquement.
Pour éviter la prochaine fois Rattacher le domaine et créer le CNAME dans la même séance, puis vérifier le statut avant d'annoncer l'adresse.
404 Not Found sur une page qui existe en local
Ce que ça veut dire La page n'a pas été générée, ou son adresse diffère (barre oblique finale, majuscules).
Correction Comparer l'adresse locale et l'adresse publique caractère par caractère. Regénérer le build et vérifier la liste des pages produites.
Pour éviter la prochaine fois Utiliser des noms de fichiers en minuscules, sans espace ni accent, et tester les liens depuis la page d'accueil.
Port 4321 is in use, trying another one…
Ce que ça veut dire Un autre projet tourne déjà sur le port par défaut : votre serveur change de port en silence.
Correction Arrêter l'autre serveur, ou donner un port stable au projet (DEV_PORT dans .env) et rouvrir le terminal.
Pour éviter la prochaine fois Un port par projet, inscrit dans .env ; et vérifier l'adresse réelle avant de partager un lien de test.
npm test échoue selon le terminal / wrangler exige Node 22
Ce que ça veut dire Le terminal n'utilise pas la même version de Node : les outils ne se comportent pas pareil.
Correction Utiliser les lanceurs du projet (scripts/run-with-node22.mjs), ou activer Node 22 dans le shell courant.
Pour éviter la prochaine fois Laisser les scripts du projet choisir la version : npm test et npm run dev s'en occupent.
Une image ou un lien ne s'affiche pas en ligne (mais en local, si)
Ce que ça veut dire Le chemin diffère par une majuscule, un accent ou un espace — invisible sur Windows, fatal sur le serveur.
Correction Renommer le fichier en minuscules, sans accent ni espace, puis corriger le lien et repousser.
Pour éviter la prochaine fois Adopter une convention de noms dès le début : minuscules, tirets, pas d'accents dans les fichiers du site.
Aucune panne ne correspond à cette recherche.
Demander de l'aide efficacement
Quand la recherche ne suffit pas, la qualité de la question fait gagner du temps à tout le monde. Un message utile contient toujours ces cinq éléments :
- Le but : « je veux que la page affiche un tableau ».
- Ce que vous avez fait : la commande, le clic, le prompt envoyé.
- Ce qui devait se passer, et ce qui se passe.
- Le message d'erreur complet, copié, jamais paraphrasé.
- Ce que vous avez déjà essayé et ce que ça a changé.
Attention : si un secret apparaît dans le message d'erreur, remplacez-le par [secret masqué] avant d'envoyer — à l'enseignant comme à un agent.
Pour aller plus loin
OpenCode
Clé, dossier, sessions, compactage : les réglages qui évitent la moitié des pannes.
DépôtGit et GitHub
Le vocabulaire et les commandes, pour comprendre les messages de Git.
PublicationCloudflare Pages
Journal de build, réglages, domaine personnalisé.
UrgenceSécurité
Procédure en cas de fuite de clé ou de secret.