#Erreurs

Chaque message que le CLI peut afficher, ce qu’il signifie, et le geste à faire. Les libellés ci-dessous sont exactement ceux du code : tu peux les chercher tels quels.

#Comment lire une erreur

Une erreur du CLI tient en deux lignes : la phrase, puis le geste, en gris. Aucune trace de pile n’en sort — elle désignerait notre code à quelqu’un qui vient de taper une commande, et masquerait la seule phrase qui lui serait utile.

Sortie du CLIbash

✗ Ta clé n'est plus valable (401).
  Relance `node scripts/theme.mjs connexion` pour en enregistrer une neuve.

✗rouge

Une erreur. Le processus sort en code 1.

!jaune

Un avertissement. La commande continue — voir la dernière section.

✓vert

Le bilan d’une commande réussie.

Astuce

--verbeux fait deux choses différentes : il détaille les appels HTTP (méthode, adresse, configuration effective), et il rend la trace technique quand l’erreur n’est pas une erreur prévue. Une erreur inattendue le dit d’ailleurs elle-même :

bash

✗ fetch failed
  `--verbeux` pour le détail technique.

#Avant le premier appel

Ces erreurs sortent sans qu’aucune requête n’ait été faite.

Message	Cause	Que faire
`Aucune clé d'API : impossible de s'authentifier.`	Rien d’enregistré, et pas de `WEBCOSA_CLE`.	`node scripts/theme.mjs connexion`, ou pose la variable d’environnement.
`Commande inconnue : « puhser ».`	Faute de frappe. Le CLI liste les commandes connues.	Les six noms français, leurs alias anglais, ou `aide`.
`Option inconnue : --dosier.`	Faute de frappe sur une option.	`node scripts/theme.mjs aide` liste les options.
`L'option --site attend une valeur : --site=<valeur>.`	Option écrite sans sa valeur.	Colle la valeur avec un `=`, ou passe-la en argument suivant.
`…/.webcosa.json` est illisible : …	Fichier de configuration présent mais mal formé.	Ouvre-le : c’est presque toujours une virgule en trop dans le JSON.
`Cette commande a besoin d'un terminal pour poser une question.`	Une confirmation ou une saisie sans TTY.	En intégration continue, passe par les variables d’environnement, ou `--force` / `--depuis-stdin`.
`Interrompu — aucune réponse saisie.`	`Ctrl+D` sur une question.	Relance.
`Aucune clé saisie.`	`connexion` avec une saisie vide.	Colle la clé complète, `wc_` compris.

#Le réseau

Message	Cause	Que faire
`Personne ne répond sur http://localhost:3000.`	Connexion refusée. Le serveur est éteint, ou le port n’est pas celui-là.	Lance `npm run dev`, ou corrige `--url`.
`Adresse introuvable : https://cms.webcosa.co.`	Le nom d’hôte ne résout pas.	Vérifie `--url` — c’est presque toujours une lettre en moins dans le domaine.
`Certificat TLS refusé par https://…`	Certificat expiré ou non vérifiable.	Certificat du serveur à renouveler. Ne contourne pas la vérification.
`Appel à … impossible : …`	Tout autre échec réseau.	`--verbeux` pour la cause exacte.
`…/api/themes n'a pas répondu du JSON.`	On ne parle pas au CMS : page de connexion, proxy d’entreprise, tunnel expiré.	Vérifie que `--url` désigne bien le CMS, pas la vitrine ni le site du client.

Note

Le dernier cas mérite d’être connu, parce qu’il ressemble à une panne du serveur alors que c’est une erreur d’adresse. Le CLI le détecte plutôt que de planter dix lignes plus loin sur un champ indéfini — mais il ne peut pas deviner quelle adresse tu voulais.

#Le serveur refuse

Les codes du contrat d’API, traduits par le CLI.

Message	HTTP	Cause	Que faire
`Ta clé n'est plus valable (401).`	401	Révoquée, périmée, ou créée sur un autre CMS. Le serveur ne dit pas laquelle des trois.	Relance `connexion` avec une clé neuve.
`Cette clé n'a pas la portée nécessaire pour écrire (403).`	403 `portee_insuffisante`	Clé de portée `lecture` sur `pousser`, `suivre` ou `publier`.	Crée une clé de portée `themes`. La portée ne se modifie pas après coup.
`Ce site n'est pas accessible avec cette clé (403).`	403 `site_interdit`	Le `--site` demandé n’est pas dans les sites du porteur.	Vérifie le slug. L’option désigne un site, elle ne l’autorise pas.
`Ce compte n'a aucun site (409).`	409 `no_site`	Le compte porteur de la clé n’a aucun site.	Rien à viser : crée un site dans le CMS.
`Ce site n'est plus actif : ses modifications sont bloquées (402).`	402 `site_inactif`	Essai terminé ou abonnement suspendu. Ce n’est pas un problème de clé.	Reprends un abonnement depuis le CMS (Réglages → Abonnement).
`Trop de tentatives avec une clé refusée (429).`	429 `trop_de_tentatives`	Dix clés invalides présentées dans l’heure, comptées par empreinte.	Attends une heure, ou repars d’une clé valable. Regarde surtout ce qui rejoue une clé morte en boucle.
`Le serveur ne sait pas vérifier les clés en ce moment (503).`	503 `indisponible`	La clé de service manque de la configuration du serveur.	Côté serveur, pas côté toi. Signale-le.
`Ce thème n'existe pas sur ce site (404).`	404 `introuvable`	Le thème visé n’est pas de ce site — ou plus.	`lister` pour les identifiants réels. Vérifie aussi le `theme` de ton `.webcosa.json`.
`Le serveur a refusé : <code> (HTTP <statut>).`	—	Un code que ce CLI ne traduit pas encore.	Le code est celui du contrat d’API.

Attention

Le 429 ne protège pas d’une recherche exhaustive de secret — 256 bits ne se devinent pas, et chaque essai différent aurait de toute façon son propre compteur. Il arrête le cas réel et fréquent : une intégration continue qui rejoue une clé révoquée, plusieurs fois par minute, indéfiniment. Si tu le reçois, l’utile n’est pas d’attendre une heure, c’est de trouver le runner fautif.

#Le thème visé

Message	Cause	Que faire
`Ce site n'a aucun thème.`	Site vierge.	Installe un thème depuis le CMS (Apparence → Thèmes), ou `pousser --nouveau`.
`Ce site a 3 thèmes : précise lequel avec --theme=.`	Plusieurs thèmes, aucune désignation. Le CLI liste les identifiants courts et les noms.	Ajoute `--theme=`, ou travaille depuis un dossier qui a son `.webcosa.json`.
`Aucun thème ne correspond à « atelier ».`	Ni identifiant, ni préfixe, ni nom exact.	Le nom doit être exact ; le préfixe, lui, suffit à huit caractères.
`« 1 » désigne 2 thèmes à la fois.`	Un préfixe trop court, commun à plusieurs identifiants.	Allonge-le. Le CLI affiche les identifiants complets concernés.

Deviner le thème sur une commande qui écrit, c’est écrire dans le mauvais thème une fois sur deux : le refus est délibéré.

#Le dossier local

Message	Cause	Que faire
`Aucun fichier de thème dans /Users/….`	Le dossier ne contient aucun des six dossiers du format, ou ils sont vides.	Vérifie `--dossier`. Attendus : `layout/ sections/ snippets/ assets/ config/ templates/`.
`assets/theme.css dépasse 512 ko : le serveur le refusera.`	Fichier au-dessus de `TAILLE_MAX`.	Découpe-le. La borne est comptée en caractères, pas en octets — voir Le bac à sable.
`143 fichiers : un thème est limité à 120.`	Au-dessus de `FICHIERS_MAX`.	Le plus souvent, un dossier de travail qui contient autre chose qu’un thème.
`Lecture de /Users/… impossible : …`	Permissions, ou lien symbolique cassé.	Erreur du système de fichiers, pas du CLI.

#À la récupération

Message	Cause	Que faire
`Le thème « Origo » n'a aucun fichier.`	Thème vide côté serveur.	Rien à récupérer. Vérifie que c’est bien le thème voulu.
`Récupération annulée, rien n'a été écrit.`	Tu as refusé d’écraser des fichiers locaux qui diffèrent.	Pousse d’abord tes modifications, ou passe `--force`.
`Le serveur a renvoyé un chemin que je refuse d'écrire : « … ».`	Un chemin hors format dans l’archive reçue.	Ne devrait jamais arriver. Rien n’a été écrit sur le disque — signale-le.
`Contenu illisible pour « … ». Rien n'a été écrit.`	Un champ de l’archive n’est pas une chaîne.	Idem : archive anormale, aucune écriture partielle.

#Le contenu refusé à l’écriture

Ces messages viennent du serveur et sont préfixés par le fichier fautif. Ils interrompent pousser ; sur suivre, ils s’affichent sans arrêter le suivi.

Sortie du CLIbash

✗ sections/hero.liquid — tag "for" not closed, line:14, col:1 [syntaxe]

Code	Message du serveur	Cause
`syntaxe`	le message de l’analyseur, avec ligne et colonne	Liquid mal formé. Le contrôle porte sur la syntaxe, pas sur le sens : une variable inconnue passe et rend du vide.
`syntaxe`	`JSON invalide : …`	Un `.json` de `config/` ou `templates/` mal formé.
`invalid_input`	`Fichier trop volumineux ou chemin invalide.`	Chemin plus court que 3 ou plus long que 120 caractères, ou contenu au-delà de la borne.
`hors_dossier`	`Ce fichier n'est dans aucun dossier connu. Attendus : …`	Un chemin à un seul segment, ou un dossier inventé.
`extension`	`Ce type de fichier n'est pas accepté dans ce dossier.`	Un `.js` dans `assets/`, un `.json` dans `sections/`.
`traversee`	`Ce chemin sort du thème.`	`..`, une barre oblique initiale, ou une barre inversée.
`nom`	`Ce nom de fichier contient des caractères qui ne passent pas.`	Le nom doit commencer par une lettre ou un chiffre, puis n’utiliser que lettres, chiffres, points, tirets et tirets bas.
`trop_de_fichiers`	`Un thème est limité à 120 fichiers.`	Le plafond est vérifié à la création d’un fichier ; un thème déjà au plafond reste modifiable.
`fichier_requis`	`Ce fichier est indispensable au thème : il ne peut pas être supprimé.`	`pousser --supprimer` sur `layout/theme.liquid`, `templates/index.json` ou `config/settings_schema.json`.
`archive_invalide`	`Ce fichier n'est pas un thème Webcosa…`	`pousser --nouveau` avec une archive que le serveur ne sait pas lire.
`fichier_requis_manquant`	`Il manque un fichier indispensable. Attendus : …`	`pousser --nouveau` sans les trois fichiers minimaux.

Note

Les libellés des refus de chemin existent en deux versions. Le CLI a les siennes, plus courtes, pour les fichiers qu’il ignore en local (extension non admise dans ce dossier) ; le serveur a les siennes, plus longues, pour ce qu’il refuse (Ce type de fichier n’est pas accepté dans ce dossier.). Même cause, deux formulations — c’est le prix d’un contrôle fait des deux côtés, et c’est préférable à un seul contrôle.

#Les commandes annulées

Ce ne sont pas des pannes : ce sont des refus que tu as donnés, ou que l’absence de terminal a donnés pour toi. Elles sortent quand même en code 1, pour qu’un script ne les prenne pas pour un succès.

Message	Quand
`Récupération annulée, rien n'a été écrit.`	Réponse « non » à l’écrasement de fichiers locaux.
`Suppression annulée — les fichiers poussés ci-dessus, eux, sont bien enregistrés.`	Réponse « non » à `--supprimer`. L’envoi, lui, a bien eu lieu.
`Suivi annulé.`	Réponse « non » à la duplication d’un thème publié. `--oui-je-sais` force le suivi du publié.
`Publication annulée.`	Réponse « non » à `publier` — ou absence de terminal, puisque la confirmation rend alors « non ».
`Interrompu.`	`Ctrl+C` pendant la saisie de la clé.

Attention

Sans terminal, toute confirmation vaut « non ». C’est le bon défaut — un script qui ne peut pas répondre ne doit pas être réputé avoir dit oui — mais cela veut dire que pousser --supprimer et publier échouent en intégration continue. Le premier a une échappatoire (--force), le second n’en a pas, et n’en aura pas.

#Les avertissements ne sont pas des erreurs

Ils commencent par !, s’affichent en jaune, et la commande continue. Les ignorer est parfois le bon choix — mais deux d’entre eux annoncent une perte.

Avertissement	Ce qu’il faut en faire
`ignoré : assets/menu.js — extension non admise dans ce dossier`	Le fichier n’a pas été envoyé, et ne le sera jamais. Si ton thème en dépend, il ne fonctionnera pas en ligne.
`… est lisible par d'autres comptes de cette machine (mode 644). Il contient ta clé`	`chmod 600` sur le fichier, ou relance `connexion`, qui réécrit correctement.
`Cette clé ne commence pas par wc_ — ce n'est probablement pas la bonne.`	Tu as sans doute collé un jeton Supabase ou un identifiant de site.
`… est sous le themes/ du dépôt — celui des thèmes d'ORIGINE`	Déplace ton dossier de travail. Un thème récupéré là finirait au catalogue.
`2 fichier(s) existent à distance mais pas en local — non touchés`	Quelqu’un a ajouté des fichiers depuis le CMS, ou tu as supprimé les tiens. Ne passe `--supprimer` qu’après avoir lu la liste.
`« Origo » est le thème PUBLIÉ : chaque sauvegarde irait en ligne.`	Accepte la copie brouillon. C’est presque toujours ce que tu veux.

Astuce

Un dernier, visible seulement en --verbeux, et qui explique bien des 401 :

bash

· la clé enregistrée l'a été pour https://cms.webcosa.com, et on appelle
  http://localhost:3000 — elle sera probablement refusée.

Une clé vaut pour une installation du CMS. Passer d’un environnement à l’autre demande de passer aussi la clé, en WEBCOSA_CLE.