Dépannage

Cette page part d'un symptôme (une construction qui échoue, un déploiement refusé, une erreur de l'API) et mène à sa cause réelle et à son remède. Elle s'appuie sur les codes que la plateforme renvoie : chacun nomme une cause, l'endroit où corriger et l'action suivante.

Où lire la cause

Un déploiement en échec porte, dans l'écran Déploiement de la console (et dans Première mise en ligne pour le premier), une carte « Pourquoi il a échoué ». Elle tient toujours trois lignes :

• la cause, en une phrase, propre à la classe d'échec ;
• Pour ce déploiement, ce que la plateforme a relevé de cet échec-ci quand elle en dit plus : un code de sortie, un état de nœud, une date ;
• Où corriger, puis À faire.

Une dernière ligne dit qui corrige : « le dépôt » (votre code ou votre configuration) ou « la plateforme » (relancez ; si l'échec persiste, il ne vient pas de vous). Quand la correction se fait dans la console, un bouton y mène : « Ouvrir les variables », ou « Corriger … dans les paramètres ». Le texte que votre dépôt a écrit (la sortie de la commande qui a échoué) s'affiche à part, dans son propre cadre : c'est le dépôt qui parle, pas la plateforme.

Par un agent, le détail se lit par deployment_read (champs failureCatalog et failureReason) et le journal par deployment_log_read.

Quand la plateforme n'a pas classé l'échec, la carte le dit : lisez le journal de construction, puis redéployez. Si l'échec revient à l'identique, signalez-le en citant l'identifiant du déploiement.

Lire une erreur de l'API

Toute erreur de l'API, de la ligne de commande et des outils MCP a la même forme :

{
  "code": "plafond_de_depense_atteint",
  "message": "…ce qu'il faut faire, en une phrase…",
  "cause": { "fr": "…", "en": "…" },
  "champ": [],
  "suite": { "genre": "aucune", "raison": "…" }
}

• code est stable : branchez votre comportement dessus, jamais sur le message.
• champ nomme les champs en faute, jamais la valeur reçue.
• suite dit l'appel suivant : un outil et ses arguments (outil), la même demande à reprendre, corrigée ou non (reprendre), ou aucune, avec sa raison (aucune).

Une 500 (internal_error) est journalisée : citez l'identifiant de requête du détail au support.

Une construction échoue

Commencez par la carte « Pourquoi il a échoué », puis par le journal. Les causes les plus fréquentes, dans l'ordre où elles surviennent :

1. La récupération du code. fetch_failed : le plus souvent, un dépôt GitHub privé auquel la plateforme n'a pas accès ; installez l'application GitHub en cochant ce dépôt, puis relancez. reference_introuvable : la branche ou le commit demandé n'existe pas.
2. La déclaration du dépôt. declaration_refusee : glowsoft.json est invalide, ou déclare plus de services ou de tâches que le palier n'en permet. controles_refuses : .bastide/controles.yaml est illisible.
3. Les variables. variables_requises_manquantes : le .env.example du dépôt déclare des variables absentes de l'environnement. Le plus simple est « Importer un .env » dans Variables.
4. La détection. framework_not_detected : rien n'est reconnu à la racine de construction ; fournissez un Dockerfile ou corrigez le répertoire racine du projet.
5. Les dépendances. dependances_en_conflit, installation_des_dependances, build_verrou_desynchronise : le manifeste ou le verrou est à corriger, puis à versionner.
6. Votre code. script_de_construction : une étape de votre construction a rendu un code non nul. commande_introuvable (sortie 127) : un outil appelé n'est pas déclaré parmi les dépendances.
7. Les bornes. build_limite_duree, build_limite_memoire, build_limite_disque, build_limite_journal, build_limite_taille : la construction a dépassé ce que le palier accorde.

Avec votre propre Dockerfile, la plateforme refuse avant de construire une instruction qu'elle ne sert pas, en citant la ligne : # syntax=, VOLUME, ONBUILD, ADD distant, un registre hors liste, une option privilégiée de RUN. Voir Constructions.

La production refuse une image vulnérable

Après la construction, l'image est analysée. Deux cas bloquent la promotion en production ; les environnements de prévisualisation se déploient comme avant :

• image_vulnerabilite_exploitee : une vulnérabilité figure au catalogue des vulnérabilités activement exploitées. Aucune dérogation ne lève ce refus.
• image_vulnerabilite_critique : une vulnérabilité de score CVSS 9,0 ou plus, qu'aucune dérogation en vigueur ne couvre.

Mettez à jour le paquet nommé à sa version corrigée, le plus souvent en reconstruisant sur une image de base plus récente, puis redéployez. Le rapport d'analyse et l'inventaire sont attachés à l'image. Une variable d'image qui a la forme d'un secret connu bloque aussi la production (image_variable_de_secret) : révoquez d'abord la valeur chez son émetteur, car elle est publiée dans une couche de l'image.

Plus aucune construction ne part

Deux plafonds arrêtent les constructions sans jamais toucher les sites en ligne :

• plafond_de_depense_atteint : la dépense de l'organisation a atteint son plafond pour le cycle. Deux personnes habilitées le relèvent depuis Facturation, ou le cycle suivant rouvre les constructions.
• quota_de_construction_atteint : le projet a consommé ses minutes de construction du mois. Elles reviennent le premier du mois suivant (UTC) ; une montée de palier les augmente tout de suite. Pour le projet gratuit, le code est quota_gratuit_construction.

Voir Facturation et Limites par palier.

Le déploiement ne passe pas en production

controles_non_satisfaits : des contrôles obligatoires déclarés pour la production ne sont pas satisfaits ; la version en ligne ne change pas. Lisez l'état des contrôles du déploiement (deployment_list), corrigez ce qui échoue, puis redéployez. Seule une personne peut passer outre, avec un motif qui reste à l'audit ; un agent reçoit contournement_reserve. Voir Contrôles.

L'application ne démarre pas, ou ne répond pas

La construction a réussi, mais la charge ne devient pas saine :

• sonde_sans_reponse : le conteneur tourne, l'application ne répond pas à la sonde dans le délai. Vérifiez qu'elle écoute sur 0.0.0.0 et sur le port de la variable PORT. Avec votre propre Dockerfile, le port vaut 3000 sauf déclaration de port dans glowsoft.json ; un EXPOSE ne suffit pas. Si l'application démarre lentement, déclarez probe.startupBudgetSeconds, et le chemin de la sonde par probe.path.
• redemarrage_en_boucle : l'application sort ou plante au démarrage, au moins trois fois. Les dernières lignes du journal jointes au déploiement montrent l'erreur : souvent une variable absente ou une base injoignable.
• memoire_depassee : le noyau a tué la charge au plafond mémoire du palier. Le rapport porte la valeur observée et la limite.
• release_sans_port : la release a été construite sans port relevé ; redéployez depuis la référence Git.

Le système de fichiers est en lecture seule, sauf /tmp : une application qui écrit ailleurs échoue au démarrage. Voir Migrer depuis un VPS pour le contrat d'exécution complet.

Le domaine reste « en attente »

Un domaine n'est servi qu'une fois sa preuve lue dans le DNS.

1. Relisez les enregistrements rendus par domain.add (ou Domaines) : un TXT de preuve, puis A et AAAA pour un apex, ou un CNAME pour un sous-domaine.
2. Le jeton TXT vaut sept jours. Rappeler domain.add sur un domaine en attente rend le même jeton et relit le DNS aussitôt.
3. domaine_deja_servi : un autre projet sert déjà ce domaine ; retirez-le de cet autre projet d'abord. domaine_reserve : le nom est sous une zone de la plateforme, il ne se rattache pas. projet_non_revendique : un projet créé par un agent doit être revendiqué par une personne avant de recevoir un domaine.

Voir Domaines.

Trop de requêtes : 429

rate_limited : le jeton a épuisé une limite de débit sur la fenêtre écoulée. Chaque jeton a 600 appels par minute, et 60 par minute pour les écritures et les lectures de secrets. Attendez le nombre de secondes de Retry-After, puis reprenez ; lisez RateLimit-Remaining pour ralentir avant le refus. trop_de_tentatives : cinq échecs de connexion en quinze minutes ; l'attente double à chaque nouvel échec. plafond_de_creations_de_projet : un agent a créé cinq projets dans la journée glissante.

Les 30 codes les plus utiles

« échec » désigne une cause inscrite sur un déploiement en échec, et non une réponse HTTP. La liste complète des codes de l'API est publiée avec chaque opération dans la référence de l'API.

Signaler un problème

Si rien ici ne correspond, écrivez au support en citant l'identifiant du déploiement (dep_…) ou l'identifiant de requête de l'erreur, et le code reçu. Ne collez jamais la valeur d'un secret.

Voir aussi : Déployer, Constructions, Journaux, Limites par palier, Questions fréquentes.

Signaler une erreur sur cette page