Discipline de traduction des erreurs
Le pipeline de compilation d’Aggrega émet des erreurs depuis de nombreuses surfaces — les validateurs de schéma, le résolveur, le constructeur de l’IR, les fournisseurs, le moteur de templates Go et les bibliothèques YAML / Helm / docker-compose sous-jacentes qu’enveloppent les fournisseurs. Les erreurs qui remontent jusqu’à la CLI commencent par un en-tête entre crochets qui nomme jusqu’à deux éléments — une catégorie, qui indique quel domaine examiner (pour la plupart des valeurs, la surface de rédaction en cause), et le code court de la condition qui a interrompu la compilation — suivi d’un pointeur de source et d’un message. Lorsqu’un plugin a levé la condition, le code est qualifié par le plugin qui l’a levée, car plusieurs plugins peuvent signaler la même condition. Cette page documente la forme de cette sortie afin que les auteurs interprètent directement les messages d’erreur.
Pour le catalogue des erreurs une à une (chaque arrêt fatal avec des indications de correction), voir fatal-halts.md. Pour les quatre couches de validation de schéma et la manière dont leurs formes d’erreur interagissent, voir vocabulary/validation-surface.md.
Les catégories d’erreur
Une étiquette de catégorie indique quel domaine examiner. La plupart nomment la surface de rédaction où se trouve la correction ; les autres nomment un domaine qui n’est l’erreur de rédaction de personne — l’acquisition d’un artefact, un verdict de gouvernance, ou la confiance et la signature — et le code court à côté de la catégorie dans l’en-tête est ce qui identifie la condition précise dans tous les cas :
[DEVELOPER_ERROR]— l’échec relève de la rédaction de l’Aggregate. La correction se trouve dans le YAML de l’Aggregate ou dans la partie du catalogue rédigée par le développeur (valeurs de Component, socketsuses, rattachements de Feature). Surfaces d’exemple : arrêts du résolveur sur des problèmes côté Aggregate ; violations de sélecteur et deappliesTosur ce que l’Aggregate a écrit.[OPS_ERROR]— l’échec relève des documents propres à l’opérateur, la Release et le Manifest. La correction se trouve dans le YAML de la Release (topologie des frontières, valeurs des paramètres, rattachements de Feature au niveau de la Release) ou dans le YAML du Manifest (la Recipe par laquelle un type est déployé, et les liaisons d’annotation écrites à côté). Surfaces d’exemple : validation du schéma de la Release ; évaluation des templates de chemins de frontière ; collisions desubDirectoryentre fournisseurs ; refus de mappings et de liaisons d’annotation du Manifest ; une règle refusant une connexion que la Release câble, ou un rattachement qu’elle remplit sur une connexion — le sélecteur d’un socket, le sélecteur d’un emplacement, un emplacement qu’un socket déclare obligatoire ; une règle refusant une Feature que seule la Release rattache, à un composant ou à une frontière — leappliesTode la Feature, le sélecteur d’un emplacement, son schéma déclaré.[CATALOG_ERROR]— l’échec relève d’une entité du catalogue (Recipe, FeatureRecipe, Component, Feature, Plugin). La correction se trouve dans le contenu du catalogue. Surfaces d’exemple : règles de forme de la Recipe ; vérifications croisées defeaturesSchemadu Workload ; erreurs d’analyse de templates dans les templates rédigés dans le catalogue.[TRANSLATION_ERROR]— l’échec relève de la synthèse côté fournisseur (un plugin de fournisseur qui tente de traduire un Workload, la sortie d’un valuesMapping ou une surcouche sourcée en artefacts natifs du fournisseur). La correction se trouve généralement dans la formeservices/containers/volumesdu Workload, dans la sortie du templatevaluesMappingde la Recipe ou dans la structure de la surcouche en mode source.[FETCH_ERROR]— l’échec relève de la récupération d’une dépendance épinglée depuis un registre ou une source distante, et non d’une surface de rédaction. La correction est généralement opérationnelle : s’authentifier auprès du registre (docker login <registry>), rétablir la connectivité, ou réépingler un artefact qui a dérivé ou a été altéré (aggrega pull --upgrade --release <release>). Surfaces d’exemple : une entité de catalogue ou un chart introuvable dans le registre ; authentification requise ou échouée ; réseau injoignable ; le digest d’un artefact en cache qui ne correspond pas au lockfile. Les erreurs de récupération portent dans le message un pointeur concret vers la correction.[POLICY_ERROR]— la compilation a été rejetée par un plugin de politique rattaché à un rôle de verdict de gouvernance. Il ne s’agit pas d’une faute de surface de rédaction : l’entrée est bien formée, mais elle échoue à une règle de gouvernance (conformité, FinOps ou sécurité) que le plugin impose. La correction consiste à mettre ce que vous avez rédigé en conformité avec la politique imposée, ou à reconsidérer le rattachement de la politique. Le message nomme le plugin qui a rejeté et porte le message de règle qu’il a fourni.[TRUST_ERROR]— la couche de confiance et de signature a refusé l’opération. Cette catégorie nomme un domaine plutôt qu’une surface de rédaction, et elle couvre deux remèdes que vous pouvez distinguer grâce au code court à côté. Votre configuration de confiance est erronée : une politique de confiance illisible, une racine de confiance épinglée impossible à charger, une politique keyless ne déclarant aucune identité de confiance, une politique de signature exigeant une signature pour le type d’artefact que vous publiez, ou un plugin enregistré comme fiable pour un rattachement de verdict que votre configuration ne rattache plus. Cet artefact a échoué à la vérification : une signature qui ne se vérifie pas par rapport à l’ancre de confiance, un artefact sans signature là où une signature est requise, une signature provenant d’un signataire réel mais non approuvé, ou un plugin dont l’identité de confiance enregistrée ne correspond plus à ce qui est résolu. Dans le premier cas, la correction se trouve dans votre configuration ou dans l’enregistrement de confiance commité ; dans le second, c’est une décision concernant l’artefact — restaurer celui qui a été revu, ou revoir et réenregistrer ce qui a changé.
Un constat sur un rattachement de Feature suit le document qui l’a écrit
Une Feature peut être rattachée dans l’un ou l’autre document — l’Aggregate en rattache une sur un composant ou sur un sous-système, la Release sur son entrée pour un composant ou sur une frontière — de sorte que la catégorie d’un constat sur un rattachement se lit d’après l’endroit où le rattachement a été écrit, et non d’après le composant qu’il atteint. Le constat est positionné sur l’entrée features: qui a écrit le rattachement, dans ce document, et il est classé sous l’auteur de ce document : un rattachement que seule la Release effectue est signalé au chemin propre de la Release comme [OPS_ERROR], et un rattachement effectué par l’Aggregate au chemin de l’Aggregate comme [DEVELOPER_ERROR].
[OPS_ERROR E0007] release.yaml at .spec.boundaries.main.components.app.features.metrics selector violation ("component.aggrega.ai/type in (server, worker)", declared by Feature "core/prometheus-exporter", not satisfied by the labels of "app"). Add the labels the Feature's appliesTo requires to this component's type, or attach a Feature whose applicability the component already satisfies.Lorsque les deux documents écrivent un même rattachement — l’Aggregate nommant sa Feature, la Release la dimensionnant — un constat sur le rattachement dans son ensemble est positionné là où sa Feature est nommée, c’est-à-dire dans l’Aggregate. Un constat sur une partie de sa configuration est positionné là où cette partie a été écrite : ses values relèvent du développeur, dans l’Aggregate, et son infra de l’opérateur, dans la Release. Un rattachement produit par l’expansion pilotée par les annotations n’a été écrit par aucune entrée features:, donc un constat le concernant est positionné sur le composant, dans le document qui déclare le composant, comme [DEVELOPER_ERROR].
Un emplacement obligatoire laissé vide est le seul cas qu’aucun document n’a écrit. Il n’y a aucun rattachement vers lequel pointer, donc le constat reste sur le composant dans l’Aggregate et il est classé comme [DEVELOPER_ERROR], et son remède nomme les deux documents, car l’un ou l’autre peut remplir l’emplacement : « Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it. » (Rattachez une Feature sous ce nom, dans l’Aggregate ou dans la Release, sur le composant ou à une portée supérieure.)
L’éditeur lit le même placement : un constat positionné dans la Release est affiché sur le document de la Release, sur la clé qui l’a écrit, et pas du tout sur celui de l’Aggregate ; un constat positionné dans le document d’un module que l’Aggregate importe est affiché de la même manière sur le document de ce module.
Forme de la sortie
Un diagnostic imprimé commence par l’en-tête entre crochets et le pointeur de source, et place le message sur sa propre ligne en retrait :
[CATEGORY SHORTCODE] <source> <message>L’en-tête porte deux jetons, qui répondent à des questions différentes. La catégorie est l’une de celles décrites ci-dessus et indique quel domaine examiner. Le code court est la lettre E suivie de quatre chiffres, et il nomme la condition exacte qui a arrêté la compilation : citez-le dans un rapport, saisissez-le dans une recherche ou résolvez-le dans la table de toutes les conditions de sentinels.md. Aucun des deux ne se déduit de l’autre, c’est pourquoi les deux sont imprimés — et lorsqu’une catégorie couvre plus d’un remède, comme c’est le cas de [TRUST_ERROR], c’est le code court qui vous indique celui auquel vous avez affaire.
Un code levé par un plugin est qualifié par le plugin qui l’a levé
Chaque code court nomme une condition qu’Aggrega déclare, et deux conditions n’en partagent jamais un : une condition déclarée sous un numéro qu’une autre condition détient déjà est refusée avant que le compilateur ne lise la moindre entrée. Un plugin n’attribue aucun code qui lui soit propre. Lorsqu’il signale un échec, il nomme l’une des conditions qu’Aggrega déclare — l’une des quelques conditions générales décrivant la manière dont un plugin a échoué, ou une condition plus spécifique lorsqu’il en existe une qui convient — et fournit la phrase qui dit ce qui s’est réellement passé. Deux plugins peuvent donc signaler le même code court, et lorsqu’ils le font, ils signalent la même condition.
Ce que le code ne peut pas dire, c’est quel plugin a rencontré la condition, et un en-tête signalant une condition levée par un plugin porte l’identité du plugin juste avant le code :
[CATEGORY PLUGIN/SHORTCODE] <source> <message>Le code court est toujours le segment final — la lettre E suivie de quatre chiffres, après le dernier /. L’identité d’un plugin comporte ses propres séparateurs, et peut comporter une version ; c’est donc la lecture depuis la fin plutôt que depuis le premier / qui permet de retrouver le code à partir de n’importe quel en-tête. Tout ce qui précède ce segment final est le plugin.
Le segment final se résout comme n’importe quel autre code court, quel que soit le plugin qui l’a levé : la table de toutes les conditions de sentinels.md le répertorie, et aggrega explain le résout. Citez le segment final seul — le qualificatif indique quel plugin a rencontré la condition, et non de quelle condition il s’agit. Un plugin qui nomme un code qu’Aggrega ne déclare pas — un numéro qu’aucune condition ne détient, ou un numéro retiré — ne voit pas ce code imprimé : la compilation s’arrête sur E0293, qualifié par ce plugin, et son message cite le code proposé par le plugin, nomme ces conditions générales et conserve la phrase du plugin lui-même.
Un en-tête qui imprime un code court nu signale une condition levée par Aggrega elle-même, ce qui inclut le cas où un plugin a échoué sans nommer de condition qui lui soit propre. Dans ce cas, c’est la condition générique d’échec de plugin du compilateur qui a arrêté la compilation, et le message du plugin en donne le détail.
L’un ou l’autre jeton peut être absent, et un jeton absent est omis
Rien ne remplace jamais un jeton que le diagnostic n’a pas — aucun espace réservé, aucun crochet vide. Un en-tête peut être raccourci de trois façons, et chacune vous apprend quelque chose :
- Pas de code court. L’échec ne nomme aucune condition propre à Aggrega — le plus souvent, il s’agit d’une erreur signalée par une bibliothèque que le compilateur encapsule. L’en-tête imprime la catégorie seule, de sorte que vous savez quand même quelle surface examiner.
- Pas de catégorie. L’échec n’a aucun domaine vers lequel vous orienter, donc aucun n’est deviné. L’en-tête imprime le code court seul, et c’est le code que vous résolvez. Deux situations le produisent, et elles se lisent de la même façon parce que, pour ce qui vous concerne, elles sont identiques — aucune ne vous dit où regarder, et le code vous dit ce qui s’est passé. L’une est un défaut du compilateur lui-même, où le message le dit et vous demande de le signaler ; le cas qui se présente est celui où les vues du compilateur sur le catalogue se contredisent. L’autre est un échec qui nomme une condition mais n’a jamais traversé de surface qui le classe sous un domaine, ce qui est la forme habituelle d’un refus levé à la limite de la commande. Une catégorie n’est jamais inventée pour combler le manque, et c’est là le but de l’omission plutôt qu’une de ses limites : la catégorie répond à « quel domaine dois-je examiner », et une réponse fournie là où la question n’en a pas n’est pas une réponse prudente mais une réponse fausse, sur laquelle on agit en premier. Il faut aussi préciser que l’inférence inverse ne tient pas : un en-tête qui porte bien une catégorie ne pointe pas toujours vers quelque chose que vous avez rédigé, car
[FETCH_ERROR],[POLICY_ERROR]et[TRUST_ERROR]nomment chacun un domaine plutôt qu’une surface de rédaction. - Ni l’un ni l’autre. Les crochets sont entièrement omis et le diagnostic se réduit à son message. Il s’agit d’un échec qui ne nomme aucune condition propre à Aggrega et n’a aucun domaine vers lequel vous orienter : une commande qui refuse ses arguments, un fichier qu’elle ne peut pas lire, une annulation, ou une erreur signalée par une bibliothèque que le compilateur encapsule sans aucune condition de notre part en dessous. Il n’y a rien à résoudre dans
sentinels.md, et le message est tout ce que l’échec a à dire.
La même erreur réduite à une ligne, la forme adaptée à la sortie de journal plutôt qu’à un terminal, porte la catégorie et omet le code court :
[CATEGORY] <source>: <message>Une catégorie absente de l’en-tête est absente ici aussi, crochets compris, de sorte que cette ligne n’est jamais [] <source>: <message>. La forme sur une ligne est ré-encapsulée dans les cadres englobants à mesure que l’échec remonte, de sorte qu’une étiquette vide serait reportée dans chacun d’eux.
La source est un pointeur structuré — généralement <file>:<line>:<column> lorsqu’une position YAML est disponible, ou un identifiant logique (le nom de l’entité du catalogue, le nom de la Release, le chemin de la frontière) lorsqu’aucune position de fichier ne s’applique. Une troisième forme, <file> at <key>, apparaît lorsque le pointeur connaît à la fois le document et la clé de rédaction qu’il contient, mais aucune position en octets : le fichier est ce que vous ouvrez, et la clé est ce qu’il faut regarder une fois le fichier ouvert. Le message est le diagnostic propre à la surface.
Un échec qui concerne une instance de votre build — un composant, un composant qu’un module fournit, ou un module lui-même — nomme cette instance après la position, sous la forme (instance <name>) ; ainsi, aggregate.yaml (instance shop) est l’Aggregate qui déclare le module shop. Lorsque l’échec n’a aucun document vers lequel pointer, l’instance figure seule, sous la forme instance <name> : un provider qui échoue pendant le rendu du composant adminer affiche [TRANSLATION_ERROR E0082] instance adminer, et les lignes en dessous portent le reste de l’échec, y compris tout document qu’il nomme. Le nom est celui sous lequel l’Aggregate déclare le composant ; un composant qu’un module fournit est nommé par son chemin à travers le module, par exemple shop.cart. Une instance n’est jamais affichée là où un fichier est attendu, de sorte que ce par quoi commence la source est un document que vous pouvez ouvrir, ou l’un des identifiants logiques ci-dessus.
Une règle évaluée sur le graphe achevé signale dans cette troisième forme, et c’est la clé qui distingue deux constats lorsque le message seul ne le peut pas. Une règle de ce type nomme le type de composant déclarant plutôt que l’instance, de sorte que deux composants d’un même type qui enfreignent la même règle portent le même message sur le même fichier :
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.checkout missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.inventory missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")La clé est la seule partie qui diffère, et c’est elle qui indique lequel des deux composants modifier. Les deux constats portent le même code court parce qu’ils sont la même condition, rencontrée deux fois — le code court nomme la règle, et la clé nomme l’occurrence.
Deux lignes supplémentaires font partie de la forme, pour un échec qui porte le contexte nécessaire pour les remplir — l’expression de template qui a échoué, et un instantané des piliers disponibles là où elle a échoué :
[CATEGORY SHORTCODE] <source> <message> expression: <the template excerpt that triggered the failure> active pillars: <one line per top-level pillar key in scope at the point of failure>La ligne expression: porte l’extrait de template qui a déclenché l’échec. Le bloc active pillars: liste les clés de pilier de premier niveau disponibles au point d’échec, afin que les auteurs voient ce qui pouvait être interrogé. Les deux sont omis lorsque l’échec ne porte ni l’un ni l’autre.
Cadres de contexte imbriqués
Une erreur traverse souvent plus d’une surface en chemin vers la CLI : une phase de chargement encapsule l’échec propre à l’entité, qui encapsule lui-même une sentinelle expliquant la règle. Chaque cadre catégorisé d’une telle chaîne est rendu — le plus externe comme en-tête dans la forme ci-dessus, chaque cadre imbriqué comme une continuation caused by: en retrait portant sa propre étiquette de catégorie, son propre pointeur de source et son propre message. Le cadre le plus interne pointant vers un fichier est toujours visible :
[CATALOG_ERROR E0094] aggrega-catalog catalog load caused by: [CATALOG_ERROR] aggrega-catalog/recipe/compose/mariadb-copy/1.0.0/recipe.yaml duplicate entity identity within a single catalog directory (recipe identity "compose/mariadb:1.0.0")Seul l’en-tête porte un code court, et les continuations ne portent que leur catégorie. La condition est nommée une fois, à l’endroit où le lecteur rencontre l’échec ; les cadres situés sous un marqueur caused by: sont ce même échec vu plus en profondeur, de sorte que répéter son identifiant sur chacun ajouterait des lignes sans ajouter de faits. Un bloc note: n’est pas une continuation et ne suit pas cette règle — il signale les conditions d’autres documents plutôt que la même vue plus en profondeur ; la section ci-dessous le traite. Le code que l’en-tête imprime est celui que la chaîne nomme — ici la règle tout en bas — de sorte qu’un cadre de contexte de phase en haut identifie quand même la condition sous-jacente.
En lisant de haut en bas : la phase qui a échoué, puis l’entité (avec son chemin de fichier) qui en est la cause, puis la règle qu’elle a enfreinte. Un cadre imbriqué qui n’ajoute rien par rapport à son parent (même catégorie, même source, un message que le parent contient déjà) est dédupliqué plutôt que répété, et une explication terminale n’est rendue que lorsque les cadres au-dessus d’elle ne portent pas déjà son texte.
Une chaîne est plus profonde chaque fois qu’un échec traverse davantage de surfaces en remontant, et la règle tient à chaque profondeur. Un template refusé à l’intérieur du Workload synthétisé d’une Recipe en traverse trois — le nœud en cours de rendu, la surface de template de la Recipe et le template lui-même :
[CATALOG_ERROR E0060] instance db rendering node "db" caused by: [CATALOG_ERROR] recipe "mariadb" workload template caused by: [CATALOG_ERROR] workload[mariadb] template references a root the render context does not define (template "workload[mariadb]" references ".nosuchroot.database", the render context defines .context, .values, .infra, .locals, .provides, .features, .metadata, .attachment_name, .inject, .inject_raw, .steps, .source, .workload, .boundary)Lisez-la de haut en bas comme précédemment, et notez trois choses que la profondeur supplémentaire rend visibles. Le code court apparaît une fois, sur l’en-tête, quel que soit le nombre de continuations qui le suivent. Le cadre le plus interne est celui où se trouve la phrase propre à la condition, de sorte que la ligne la plus profonde est à la fois celle sur laquelle effectuer la correspondance et celle qui dit quoi changer. Et un cadre sans pointeur de source imprime sa catégorie seule : le cadre du milieu ci-dessus nomme dans son message la surface sur laquelle il a échoué, parce que cette surface est un template et non un fichier, et n’a aucune position vers laquelle pointer.
Lorsque l’échec se ramifie sous un cadre — une phase qui a collecté plusieurs violations indépendantes avant de s’arrêter — la continuation porte un décompte, et chaque échec collecté est rendu en dessous, séparé par le même trait --- que celui des chaînes multi-erreurs ci-dessous :
[OPS_ERROR E0099] recipe resolution caused by (2): [OPS_ERROR] .spec.components.edge no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.edge, "edge", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it --- [OPS_ERROR] .spec.components.internal no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.internal, "internal", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to itLes échecs collectés sous le décompte sont eux aussi des continuations, de sorte qu’aucun d’eux ne répète le code court de l’en-tête — ce qui évite qu’une ramification d’une douzaine de violations imprime le même identifiant une douzaine de fois.
Une seule grammaire de séparateurs s’applique partout : --- entre échecs frères, caused by: entre cadres de contexte imbriqués.
Un fichier de catalogue refusé et l’échec qu’il explique
Le chargement d’un catalogue pour résoudre ce dont dépend une Release est tolérant à dessein : un fichier qui ne peut pas être lu, ou un document Aggrega qui ne peut pas être analysé ou indexé, est refusé et consigné plutôt que d’interrompre tout le chargement. C’est ce qui empêche une entité défectueuse que votre Release ne touche jamais de faire échouer une compilation sans rapport.
La conséquence est qu’un fichier refusé disparaît silencieusement du catalogue — et si votre Release l’atteint effectivement, ce qui échoue est la tentative de résoudre une référence à ce que ce fichier déclarait. Cet échec est une conséquence du refus plutôt que le refus lui-même, de sorte que le rapport place les deux dans l’ordre causal partout où il peut nommer le refus avec exactitude :
[CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema note: this file was skipped at load, so the catalog holds nothing under the identity it declares. This Release reaches that identity, so what failed is the attempt to resolve the reference to it: resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"Le refus vient en premier, avec sa propre catégorie et son propre code court, parce qu’il nomme ce sur quoi vous pouvez agir : la correction est un implements: manquant dans une Recipe, et non quoi que ce soit concernant la manière dont une référence est recherchée dans un registre. L’échec de résolution est tout de même signalé, en dessous, parce que c’est lui qui dit pourquoi ce document était nécessaire.
Un refus ne vient en premier que lorsqu’exactement un fichier refusé déclare l’identité que nomme la référence en échec. La correspondance porte sur l’identité que chaque document déclare pour lui-même — son type, son nom, sa version et, pour une recette, le spec.capability qui la délimite — de sorte qu’un fichier refusé déclarant ce que demande la référence est le fichier vers lequel cette référence se serait résolue. Deux conséquences en découlent. Une référence indiquant une plage de versions plutôt qu’une version ne nomme aucun document unique, et ne désigne donc rien. Et un document trop mal formé pour que son en-tête puisse être lu ne déclare aucune identité, de sorte qu’il n’est jamais désigné comme la cause de quoi que ce soit.
Lorsqu’aucun fichier refusé ne déclare cette identité, ou que plusieurs la déclarent, le rapport est ce qu’il serait sans registre des refus : l’échec vient en premier, et chaque refus est listé en dessous pour que vous l’évaluiez. Désigner le mauvais fichier comme cause serait pire que de n’en désigner aucun, parce que vous agiriez en conséquence.
[E0105] resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe" note: catalog files skipped at load. A refusal outside this Release's closure is tolerated and never fails a build, so this failure is explained only by a refusal naming something this Release reaches: - Recipe "server-recipe" (catalog/recipes/helm/server.yaml): [CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml: document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schemaQuelques points sur cette seconde forme méritent d’être connus, car chacun répond à une question que le bloc soulèverait autrement.
L’en-tête nomme l’échec, pas un refus. Le code court en haut est celui que l’échec de résolution a levé, parce que c’est cet échec qui vient en premier ici — aucun fichier refusé n’a été désigné, donc aucun d’eux n’ouvre la ligne. Il ne porte aucune catégorie à côté de lui, parce que rien sur ce chemin n’a classé l’échec sous un domaine. L’en-tête propre à chaque refus se trouve dans sa propre entrée en dessous, et c’est là que vous le lisez.
Chaque refus est listé, pas seulement celui qui comptait. Arriver à cette forme signifie que le registre n’a pas pu en désigner un seul ; la note énonce donc la distinction au lieu de deviner : un refus en dehors de la fermeture de cette Release est toléré et ne peut pas être ce qui a échoué, ce qui laisse un refus nommant quelque chose que la Release atteint comme la seule entrée qui explique l’échec. Lisez les entrées au regard de ce que votre Release utilise réellement.
Chaque entrée porte son propre en-tête entre crochets — sa propre catégorie et son propre code court. C’est le seul endroit où un code court apparaît sous l’en-tête du diagnostic, et ce n’est pas une exception à la règle des continuations ci-dessus mais une conséquence de celle-ci : une entrée sous note: n’est pas le même échec vu plus en profondeur, c’est une condition différente levée par un document différent. Nommer sa condition est ce qui vous permet de rechercher le refus et de corriger le fichier, ce qui est l’action que le bloc existe pour permettre.
Un fichier refusé dont l’en-tête était trop mal formé pour retrouver l’identité qu’il déclare est listé par son seul chemin. C’est la lecture honnête d’un document dans lequel rien n’a pu jeter un œil, et le chemin suffit toujours pour ouvrir le fichier. Un fichier trop mal formé pour que même son type puisse être lu — un fichier qui ne s’analyse pas comme du YAML, par exemple — est listé de cette façon lorsqu’il déclare une apiVersion Aggrega, par une ligne commençant, sans indentation, par apiVersion: et une valeur commençant par aggrega.ai/, avec la raison donnée par l’analyseur lui-même : la ligne, et ce que l’analyseur attendait à cet endroit. Un fichier YAML déclarant une autre apiVersion, ou aucune, n’est pas un document Aggrega — le template d’un chart, par exemple, ou un fichier de configuration conservé à côté des entités — et il n’est donc jamais listé, aussi mal formé soit-il.
Un fichier déclarant un type qu’aucun catalogue ne contient n’est nommé que là où il explique l’échec. Un document qui déclare une apiVersion Aggrega et un kind qu’aucun catalogue ne contient — un Componnent mal orthographié, par exemple — est ignoré par tout chargement ; ce n’est donc pas un refus, et il ne figure pas parmi eux. Lorsque la référence en échec demande le nom que ce fichier déclare, et la version là où la référence en indique une, le rapport le nomme dans une note qui lui est propre sous l’échec, quel que soit le type sous lequel la référence a été collectée — sur chaque surface listée ci-dessous, et sur aggrega build, qu’il lise un lockfile existant ou en remplisse d’abord un :
[E0114] resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from <referring paths>) note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: - Componnent "<name>" (<path>): [CATALOG_ERROR E0371] <path>: catalog document declares a kind a catalog does not hold (kind "Componnent"). a catalog holds Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary, Aggregate and Plugin documents, and passes over a Workload, a Manifest or a Release; correct the kind, or move the file out of the catalog directoriesL’échec continue de venir en premier : le type que déclare le fichier ne nomme aucune identité, de sorte que le fichier n’est jamais désigné comme le refus par lequel le rapport commence. L’explication de l’endroit d’où les entités locales sont lues est omise de ce rapport, parce que le fichier se trouve déjà là où le catalogue lit et que le déplacer n’aiderait pas. Un fichier d’un type qu’aucun catalogue ne contient qui déclare un autre nom n’explique rien de cet échec et n’est pas mentionné. aggrega serve, dont les messages tiennent sur une ligne, porte la même note sur cette ligne — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: suivi du refus du fichier — et ne liste jamais un tel fichier parmi les fichiers ignorés au chargement ; l’outil describe d’aggrega mcp, interrogé sur un nom dans les termes d’une Release, le nomme lui aussi à la place de cette explication. aggrega validate et aggrega lint sur l’ensemble du catalogue signalent chacun de ces fichiers, que quelque chose l’atteigne ou non — voir fatal-halts.md §« A catalog document declares a kind a catalog does not hold (Un document de catalogue déclare un type qu’un catalogue ne contient pas) ».
Quelle que soit la forme obtenue, l’échec conserve sa propre identité. La note est ajoutée à l’échec plutôt que rendue par-dessus, et faire venir un refus en premier ne change que ce que vous lisez en premier — la condition levée par l’échec reste donc intacte dans les deux cas : son code court se résout toujours, et un outil qui effectue la correspondance sur la condition la trouve toujours.
Lorsque le document refusé est lui-même ce qu’une commande signale, le refus est énoncé une seule fois. aggrega inspect <name> charge le catalogue de manière stricte, de sorte qu’un document que le chargement refuse l’arrête, et ce qu’elle imprime est le refus de ce document sous la forme d’un diagnostic unique : l’en-tête portant la catégorie et le code court du refus, le document comme source, et en dessous ce qui ne va pas dans le document — pour une violation de schéma, les clés en infraction avec leurs lignes et colonnes, et le conseil. Le chargement qui l’a levé est passé par le répertoire qu’il parcourait et par l’étape qui a lu le fichier, et ceux-ci ne sont pas imprimés comme des cadres à part entière, parce que chacun nommerait de nouveau le même document sans ajouter de fait. aggrega serve, interrogé sur ce à quoi un nom fait référence là où un document refusé déclare ce nom, répond avec le même refus dans les mêmes termes sur une ligne, suivi de la note indiquant que le fichier a été ignoré au chargement. Comme ci-dessus, la condition du refus reste identifiable par correspondance dans les deux cas.
Les deux formes vous parviennent partout où cette résolution s’exécute. aggrega build, aggrega pull, aggrega validate --release et aggrega inspect --closure les produisent dans un terminal, tout comme aggrega validate sur une seule Recipe dont la cible implements est introuvable, et un assistant IA connecté via aggrega mcp reçoit la même explication des outils build et validate, ainsi que le refus de tête, sur une seule ligne, lors d’une lecture catalog:// d’une entité qu’un fichier refusé déclare. La surface depuis laquelle vous avez posé la question ne change rien au fichier qu’on vous indique d’ouvrir — un appelant qui atteint aggrega mcp via HTTP se le voit indiquer relativement à la racine de l’espace de travail, et ne se voit pas indiquer un fichier situé hors de l’espace de travail que ce serveur dessert — et lorsqu’un refus vient en premier, le contrat de rédaction vers lequel pointe la réponse est celui du type que déclare ce document refusé — et non celui du type de la référence qui a échoué.
La classe d’échecs de l’enveloppe du document
Chaque document d’entité — entités du catalogue, Aggregates, Manifests, Releases — est validé par rapport au schéma JSON publié de son type au moment de son chargement, avant l’analyse typée. Un document qui viole son enveloppe (une clé inconnue, un champ obligatoire manquant, une valeur de forme incorrecte, une construction interdite telle que values: dans une Release) arrête le build de façon explicite avec un diagnostic qui nomme d’abord la condition, puis le type d’entité et le fichier, puis chaque clé ou forme fautive avec la ligne et la colonne où elle se trouve, et enfin ce qu’il faut faire :
[OPS_ERROR E0215] release.yaml document envelope validation failed (Release, at release.yaml); 12:7: spec.boundaries.main.values: against /$defs/boundary: unexpected property: "values". correct the document to match its kind's schemaLe diagnostic s’ouvre sur la condition, nomme le type et le fichier, et se termine par ce qu’il faut faire ; chaque violation entre les deux porte seulement line:column, puisque l’en-tête a déjà nommé le fichier. Chaque clé fautive est signalée à sa propre position plutôt qu’à celle du bloc qui la contient, de sorte que la ligne et la colonne pointent vers la clé que vous devez modifier. Lorsque la forme de la position provient d’une définition réutilisable du schéma, le diagnostic nomme cette définition après le mot against — against /$defs/boundary ci-dessus — afin qu’il soit clair par rapport à quel contrat la clé a été mesurée, et que la définition ne se lise pas comme une étape de plus le long du chemin de clés que vous avez écrit. Un document comportant plusieurs violations les liste chacune à sa propre position, dans l’ordre des clés, et le rapport s’arrête après quatre avec le décompte des autres.
Deux choses méritent d’être connues sur l’endroit où pointe une position, car toutes deux sont utiles plutôt que surprenantes :
- Une clé obligatoire manquante n’a pas de position propre — elle est par définition absente du document. La violation pointe plutôt vers la clé englobante, qui est l’endroit où l’entrée manquante doit figurer. Ainsi,
spec.capability: missing required propertypointe versspec:, et c’est là que vous l’ajoutez. - Une clé dont le nom contient un point — chaque étiquette
component.aggrega.ai/…et chaque annotationfeatures.aggrega.ai/…— est signalée au niveau du bloc qui la contient plutôt qu’à l’entrée elle-même, puisque les points se lisent comme des pas vers l’intérieur du document. Une violation sur une étiquette pointe verslabels:.
Lorsqu’une violation nomme une clé qui ne figure nulle part dans le document — un bloc metadata: entier omis, par exemple — la position est omise plutôt que devinée, et la violation se lit comme le seul chemin de clé suivi du message. Une position dont vous devriez vous méfier est pire que pas de position du tout.
La catégorie suit la surface de rédaction : [CATALOG_ERROR] pour les entités du catalogue, [DEVELOPER_ERROR] pour les Aggregates, [OPS_ERROR] pour les Releases et les Manifests. Le même contrôle s’exécute sur chaque surface qui charge des entités — aggrega build, aggrega lint, aggrega validate et les diagnostics d’éditeur que publie aggrega serve — de sorte qu’une clé superflue ou mal orthographiée est rejetée partout où le document est lu en premier, au lieu d’être ignorée silencieusement. Chacune de ces surfaces résout la position de la même façon, si bien qu’elles pointent vers la même clé, et chacune lit la phrase de la condition dans la condition elle-même : la ligne que votre éditeur souligne est la ligne que le terminal nomme, et la phrase par laquelle s’ouvre l’entrée de l’éditeur est celle par laquelle s’ouvre le terminal. Ce que les deux surfaces ne partagent pas, c’est le message complet, et c’est voulu — le terminal regroupe chaque constat sous un seul en-tête et se termine par le conseil pour le chemin, tandis que l’éditeur émet une entrée par constat, positionnée sur sa propre clé, sans répéter ni le fichier auquel elle est déjà rattachée ni un conseil qu’il répéterait sinon à chaque soulignement. La partie qui converge est donc celle à laquelle vous reconnaissez la condition.
Chaînes d’erreurs multiples
Lorsqu’une seule compilation détecte plusieurs violations indépendantes (le plus souvent pendant l’analyse statique, où chaque violation de sélecteur et de appliesTo est collectée avant qu’aucune n’arrête le build), les erreurs sont jointes en une seule chaîne. La CLI parcourt la chaîne et affiche chaque sous-erreur indépendamment, séparée par une ligne horizontale :
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge.uses.reviewed_upstream.internal selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.---[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge2.uses.reviewed_upstream.internal selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.Le séparateur --- est littéral — les lecteurs et les outils en aval peuvent découper sur lui pour énumérer les erreurs jointes. Chaque sous-erreur est un échec à part entière plutôt qu’un détail de sa voisine, de sorte que chacune porte son propre en-tête : sa propre catégorie et son propre code court, chacun là où elle en a un, comme le décrit la section sur les jetons absents. Deux violations d’une même règle nomment le même code court, comme ci-dessus ; deux violations de règles différentes en nomment de différents.
Lire une erreur de bout en bout
Dans la plupart des contextes de rédaction, le préfixe de catégorie et le pointeur vers la source identifient ensemble ce qu’il faut corriger :
| Catégorie | Où se trouve la correction | Surfaces d’exemple |
|---|---|---|
[DEVELOPER_ERROR] | YAML de l’Aggregate | Violations de sélecteur / appliesTo sur ce que l’Aggregate a écrit ; incohérence du socket uses côté Aggregate ; arrêts du résolveur sur la rédaction du développeur. |
[OPS_ERROR] | YAML de la Release / YAML du Manifest | Le modèle de chemin de la frontière référence un champ non pris en charge ; subDirectory provoque une collision de chemins ; arrêts du résolveur sur la rédaction de la Release ; une connexion que la Release câble, ou un rattachement qu’elle remplit sur une connexion, refusés par les règles du socket ou de l’emplacement ; une Feature que seule la Release attache, à un composant ou à une frontière, refusée par les règles de la Feature ou de l’emplacement ; un mapping ou une liaison d’annotation d’un Manifest est refusé. |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Règles de forme de la Recipe ; le template de la FeatureRecipe référence un champ propre à chaque composant avec executionScope: boundary ; le contrôle croisé featuresSchema du Workload échoue. |
[TRANSLATION_ERROR] | Workload / sortie de valuesMapping / overlay de source | Résolution du port de sonde Helm ; collision de noms de service compose entre frontières ; deux contributeurs compose déclarant un même nom de volume ou de config de premier niveau avec des corps contradictoires ; incohérence du nom de chart sur le chart parapluie helm-chart. |
[FETCH_ERROR] | Acquisition depuis le registre / une source distante (opérationnelle, pas de rédaction) | Artefact introuvable dans le registre ; authentification requise ; réseau inaccessible ; digest en cache non concordant avec le fichier de verrouillage. Correction : s’authentifier, rétablir la connectivité ou aggrega pull --upgrade --release <release>. |
[POLICY_ERROR] | Plugin de politique (règle de gouvernance) | Un plugin de politique attaché à un rôle de verdict de gouvernance a rejeté le build assemblé au regard d’une règle qu’il applique. Correction : satisfaire la politique appliquée ou reconsidérer le rattachement. |
[TRUST_ERROR] | Configuration de confiance, ou la signature propre de l’artefact (un domaine, pas une surface de rédaction) | Une politique de confiance ou une racine de confiance épinglée illisible ; une politique keyless ne déclarant aucune identité de confiance ; une politique de signature exigeant une signature pour le type en cours de publication ; une porte de rattachement de verdict enregistrée que la configuration n’attache plus. Ou : une signature qui ne se vérifie pas ; un artefact n’en portant aucune là où une est requise ; un signataire non approuvé ; un plugin dont l’identité de confiance enregistrée ne correspond plus. Correction : corriger la configuration ou l’enregistrement de confiance versionné, ou trancher au sujet de l’artefact — le code court indique lequel. |
Les préfixes de contexte par fournisseur (helm: node "<id>": ..., compose: node "<id>": ...) apparaissent dans la partie message des sorties [TRANSLATION_ERROR] et [CATALOG_ERROR] pour localiser le fournisseur en échec lorsque plusieurs fournisseurs sont en jeu.
Erreurs natives des bibliothèques
Les erreurs qui naissent dans une bibliothèque sous-jacente (erreurs de chargement de chart du SDK Helm, erreurs du parseur YAML de docker-compose, erreurs d’E/S de fichier dues à un chemin source manquant) sont enveloppées avec le préfixe de contexte par fournisseur et apparaissent sous [TRANSLATION_ERROR] ou [CATALOG_ERROR] selon qu’elles se sont déclenchées pendant la synthèse ou pendant le chargement du contenu du catalogue. Le message de bibliothèque enveloppé conserve tel quel le diagnostic de l’outil d’origine, afin que les auteurs puissent le comparer à la documentation propre de l’outil.
Références croisées
fatal-halts.md— catalogue, erreur par erreur, de chaque arrêt fatal avec son message prévu et la manière de le corriger.warnings.md— avertissements non fatals que le compilateur émet.vocabulary/validation-surface.md— les quatre couches de validation par schéma et la façon dont leurs formes d’erreur interagissent.