#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 : vous pouvez 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.
✗ Ta clé n'est plus valable (401).
Relance `webcosa theme connexion` pour en enregistrer une neuve.✗rougeUne erreur. Le processus sort en code 1.
!jauneUn avertissement. La commande continue — voir la dernière section.
✓vertLe bilan d’une commande réussie.
--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 :
✗ 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. | webcosa theme connexion, ou pose la variable d’environnement. |
Commande inconnue : « puhser ». | Faute de frappe. Le CLI propose la commande la plus proche, ou liste les connues. | Les noms français, leurs alias anglais, ou aide. |
« pousser » est une commande du groupe theme. | Une commande tapée sans son groupe. | La ligne à taper est donnée : webcosa theme pousser. |
Groupe inconnu : « sitte ». | Faute de frappe sur le groupe. | Deux groupes seulement : theme et site. |
« verifier » est une commande du groupe theme, pas du groupe site. | Les deux groupes ont un verifier, un diagnostic et un ouvrir. | Change de groupe, la ligne exacte est donnée. |
Option inconnue : --dosier. | Faute de frappe sur une option. | webcosa theme aide liste les options. |
L'option --site attend une valeur : --site=<valeur>. | Option écrite sans sa valeur. | Collez la valeur avec un =, ou passez-la en argument suivant. |
`…/.webcosa.json` est illisible : … | Fichier de configuration présent mais mal formé. | Ouvrez-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. | Collez 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à. | Lancez npm run dev, ou corrigez --url. |
Adresse introuvable : https://cms.webcosa.co. | Le nom d’hôte ne résout pas. | Vérifiez --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 contournez 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érifiez que --url désigne bien le CMS, pas la vitrine ni le site du client. |
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 vous vouliez.
#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éez 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érifiez 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éez 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é. | Reprenez un abonnement depuis le CMS (Paramètres → 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. | Attendez une heure, ou repars d’une clé valable. Regardez 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é vous. Signalez-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érifiez aussi le theme de votre .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. |
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 vous le
recevez, 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. | Installez 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. | Ajoutez --theme=, ou travaillez 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érifiez --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écoupez-le. La borne est comptée en caractères, pas en octets — voir Le bac à sable. |
543 fichiers : un thème est limité à 500. | 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érifiez que c’est bien le thème voulu. |
Récupération annulée, rien n'a été écrit. | Vous avez refusé d’écraser des fichiers locaux qui diffèrent. | Pousse d’abord vos 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 — signalez-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. |
#Créer, dupliquer, supprimer
Les commandes qui portent sur le thème en tant qu’objet.
| Message | Cause | Que faire |
|---|---|---|
Aucun thème d'origine ne s'appelle « origoo ». | nouveau --depuis= avec un identifiant inconnu. Le CLI liste les identifiants réels. | webcosa theme nouveau sans option affiche la liste avec les descriptions. |
Aucun catalogue de thèmes en /Users/…/themes. | nouveau lancée hors du dépôt, ou depuis une copie du seul scripts/. | Lancez-la depuis le dépôt, ou installez le CLI avec npm link. Ailleurs, pars de recuperer. |
/Users/… contient déjà 51 fichier(s) de thème. | nouveau sur un dossier de travail existant. | Choisissez un autre --dossier=, ou --force pour écrire par-dessus. |
« origo » n'a aucun fichier de thème sur le disque. | Le dossier du catalogue existe mais est vide. | Le catalogue est cassé, pas votre commande. Signalez-le. |
« Origo » est le thème PUBLIÉ : le retirer éteindrait l'apparence du site. | supprimer sur le thème en ligne. Le serveur le refuse aussi, en 409 theme_publie. | Publiez-en un autre d’abord. |
Un nom de thème tient en 80 caractères : le serveur refusera au-delà. | renommer ou dupliquer --nom= avec un nom trop long. | Raccourcis. Le CLI refuse avant d’envoyer. |
Aucun nom donné. | renommer avec --nom= vide, ou une réponse vide à la question. | Donnez un nom. |
#Le groupe site
| Message | Cause | Que faire |
|---|---|---|
Le serveur n'a pas nommé de site. | La réponse de /api/themes ne porte pas de slug. | Vérifiez --site=, ou que la clé a bien accès à un site. |
`--adresse=…` n'est pas une adresse valable. | Adresse mal formée. Sans https://, le CLI l’ajoute — le reste doit être une URL. | Collez l’adresse complète, telle qu’elle s’écrit dans le navigateur. |
`--pages=zéro` : il faut un nombre entier positif. | Une option numérique reçue en toutes lettres, à zéro ou négative. | --pages, --profondeur, --delai et --passages attendent un entier ≥ 1. |
Le site ne répond pas — pas de réponse en 10 s. | Le site public ne répond pas dans le délai. | Vérifiez l’adresse : sans --adresse, c’est le sous-domaine technique qui est sondé, pas un domaine personnalisé. |
Le site ne répond pas — plus de 5 redirections. | Boucle de redirections, ou chaîne anormalement longue. | Regardez vos redirections dans le CMS. |
« Dubois » n'a aucun thème à sauvegarder. | site sauvegarder sur un site vierge. | Rien à écrire. Le contenu du site n’est de toute façon pas accessible au CLI. |
Le groupe site déduit l’adresse publique du slug quand --adresse n’est pas
donnée. Un site branché sur un domaine personnalisé sera donc sondé sur son
sous-domaine technique — qui répond, mais qui n’est pas l’adresse que voient les
clients. La sortie le rappelle chaque fois qu’elle a deviné.
Ce n’est pas un oubli : les domaines d’un site (table domaines) ne sont exposés
par aucune route ouverte aux clés d’API. Voir Le groupe site.
#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.
✗ 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é à 500 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. |
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 vous avez donnés, ou que l’absence
de terminal a donnés pour vous. 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 ». |
Suppression annulée — rien n’a été touché. | Réponse « non » à theme supprimer. --force supprime sans question. |
Interrompu. | Ctrl+C pendant la saisie de la clé. |
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, theme supprimer et publier échouent en
intégration continue. Les deux premiers ont une échappatoire (--force), le
troisième 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 votre 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. | Vous avez 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éplacez votre 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 vous avez supprimé les vôtres. Ne passe --supprimer qu’après avoir lu la liste. |
« Origo » est le thème PUBLIÉ : chaque sauvegarde irait en ligne. | Acceptez la copie brouillon. C’est presque toujours ce que vous voulez. |
exclu de l’archive : assets/menu.js — extension non admise dans ce dossier | empaqueter. Le fichier n’entre pas dans le .zip, comme il n’entrerait pas dans une poussée. |
config/theme.json n’a pas pu être renommé — le nom du dossier servira. | nouveau --nom= sur un thème d’origine dont le theme.json est illisible. Renommez le thème à la poussée, avec pousser --nouveau --nom=. |
Thème publié : non vérifié | site diagnostic --adresse= sans clé. Seuls les contrôles visibles de l’extérieur sont faits — enregistrez une clé pour les neuf. |
Cette sauvegarde ne contient QUE les thèmes. | site sauvegarder. Les pages, articles et réglages passent par /api/export, qui n’accepte pas les clés : exportez-les depuis le CMS. |
Un dernier, visible seulement en --verbeux, et qui explique bien des 401 :
· 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.

