Disciplina di traduzione degli errori
La pipeline di compilazione di Aggrega emette errori da molte superfici — validatori di schema, il risolutore, il costruttore dell’IR, i provider, il motore di template Go e le librerie YAML / Helm / docker-compose sottostanti che i provider incapsulano. Gli errori che risalgono fino alla CLI si aprono con un’intestazione tra parentesi quadre che indica fino a due elementi — una categoria, che dice quale ambito esaminare (per la maggior parte dei valori, la superficie di authoring in errore), e il codice breve della condizione che ha interrotto la build — seguita da un puntatore alla sorgente e da un messaggio. Quando è stato un plugin a sollevare la condizione, il codice è qualificato dal plugin che l’ha sollevata, perché più di un plugin può segnalare la stessa condizione. Questa pagina documenta la forma di quell’output affinché gli autori interpretino direttamente i messaggi di errore.
Per il catalogo dei singoli errori (ogni arresto fatale con le indicazioni su come correggerlo), vedi fatal-halts.md. Per i quattro livelli di validazione dello schema e il modo in cui interagiscono le forme dei loro errori, vedi vocabulary/validation-surface.md.
Le categorie di errore
Un tag di categoria indica quale ambito esaminare. La maggior parte nomina la superficie di authoring in cui si trova la correzione; le restanti nominano un ambito che non è un errore di scrittura di nessuno — l’acquisizione di un artefatto, un verdetto di governance, oppure fiducia e firma — e il codice breve accanto alla categoria nell’intestazione è ciò che identifica la condizione specifica in ogni caso:
[DEVELOPER_ERROR]— l’errore riguarda la scrittura dell’Aggregate. La correzione è nello YAML dell’Aggregate o nella parte del catalogo scritta dallo sviluppatore (valori dei Component, socketuses, associazioni di Feature). Superfici di esempio: arresti del risolutore su problemi lato Aggregate; violazioni di selettore e diappliesTosu ciò che l’Aggregate ha scritto.[OPS_ERROR]— l’errore riguarda i documenti propri dell’operatore, la Release e il Manifest. La correzione è nello YAML della Release (topologia dei confini, valori dei parametri, associazioni di Feature a livello di Release) o nello YAML del Manifest (tramite quale Recipe viene distribuito un tipo, e i binding delle annotazioni scritti accanto). Superfici di esempio: validazione dello schema della Release; valutazione dei template dei percorsi dei confini; collisioni disubDirectorytra provider; rifiuti di mappature e di binding di annotazioni del Manifest; una regola che rifiuta una connessione cablata dalla Release, o un’associazione che essa riempie su una connessione — il selettore di un socket, il selettore di uno slot, uno slot che un socket dichiara obbligatorio; una regola che rifiuta una Feature che solo la Release associa, a un componente o a un confine — l’appliesTodella Feature, il selettore di uno slot, il suo schema dichiarato.[CATALOG_ERROR]— l’errore riguarda un’entità del catalogo (Recipe, FeatureRecipe, Component, Feature, Plugin). La correzione è nel contenuto del catalogo. Superfici di esempio: regole sulla forma della Recipe; controlli incrociati difeaturesSchemadel Workload; errori di parsing dei template nei template scritti nel catalogo.[TRANSLATION_ERROR]— l’errore riguarda la sintesi lato provider (un plugin provider che tenta di tradurre un Workload, l’output di un valuesMapping o un overlay con sorgente in artefatti nativi del provider). La correzione è tipicamente nella formaservices/containers/volumesdel Workload, nell’output del templatevaluesMappingdella Recipe o nella struttura dell’overlay in modalità sorgente.[FETCH_ERROR]— l’errore riguarda il recupero di una dipendenza fissata da un registry o da una sorgente remota, non una superficie di authoring. La correzione è di solito operativa: autenticarsi al registry (docker login <registry>), ripristinare la connettività, oppure fissare di nuovo un artefatto divergente o manomesso (aggrega pull --upgrade --release <release>). Superfici di esempio: un’entità del catalogo o un chart non trovato nel registry; autenticazione richiesta o fallita; rete irraggiungibile; il digest di un artefatto in cache che non corrisponde al lockfile. Gli errori di recupero contengono nel messaggio un riferimento concreto alla soluzione.[POLICY_ERROR]— la build è stata rifiutata da un plugin di policy associato a un ruolo di verdetto di governance. Non è un errore di una superficie di authoring: l’input è ben formato, ma non rispetta una regola di governance (conformità, FinOps o sicurezza) che il plugin impone. La correzione consiste nel rendere ciò che hai scritto conforme alla policy imposta, oppure nel riconsiderare l’associazione della policy. Il messaggio indica il plugin che ha rifiutato e riporta il messaggio della regola da esso fornito.[TRUST_ERROR]— il livello di fiducia e firma ha rifiutato l’operazione. Questa categoria nomina un ambito anziché una superficie di authoring, e copre due rimedi che puoi distinguere dal codice breve accanto. La tua configurazione di fiducia è sbagliata: una policy di fiducia che non può essere letta, una radice di fiducia fissata che non può essere caricata, una policy keyless che non dichiara alcuna identità attendibile, una policy di firma che richiede una firma per il tipo di artefatto che stai pubblicando, o un plugin registrato come attendibile per un’associazione di verdetto che la tua configurazione non associa più. Questo artefatto non ha superato la verifica: una firma che non si verifica rispetto all’ancora di fiducia, un artefatto senza firma dove una è richiesta, una firma di un firmatario reale ma non attendibile, o un plugin la cui identità attendibile registrata non corrisponde più a ciò che viene risolto. La correzione nel primo caso è nella tua configurazione o nel registro di fiducia committato; nel secondo è una decisione sull’artefatto — ripristinare quello revisionato, oppure revisionare e registrare di nuovo ciò che è cambiato.
Un rilievo su un’associazione di Feature segue il documento che l’ha scritta
Una Feature può essere associata in entrambi i documenti — l’Aggregate ne associa una su un componente o su un sottosistema, la Release sulla propria voce per un componente o su un confine — quindi la categoria di un rilievo su un’associazione si ricava da dove l’associazione è stata scritta, non dal componente che raggiunge. Il rilievo è posizionato sulla voce features: che ha scritto l’associazione, in quel documento, ed è attribuito all’autore di quel documento: un’associazione che solo la Release effettua viene segnalata nel percorso proprio della Release come [OPS_ERROR], e una effettuata dall’Aggregate nel percorso dell’Aggregate come [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.Quando entrambi i documenti scrivono un’unica associazione — l’Aggregate che nomina la sua Feature, la Release che la dimensiona — un rilievo sull’associazione nel suo insieme è posizionato dove è nominata la sua Feature, ovvero l’Aggregate. Un rilievo su una parte della sua configurazione è posizionato dove quella parte è stata scritta: i suoi values sono dello sviluppatore, nell’Aggregate, e il suo infra dell’operatore, nella Release. Un’associazione prodotta dall’espansione guidata dalle annotazioni non è stata scritta da alcuna voce features:, quindi un rilievo su di essa è posizionato sul componente, nel documento che dichiara il componente, come [DEVELOPER_ERROR].
Uno slot obbligatorio lasciato vuoto è l’unico caso che nessun documento ha scritto. Non c’è alcuna associazione a cui puntare, quindi il rilievo resta sul componente nell’Aggregate ed è classificato come [DEVELOPER_ERROR], e il suo rimedio nomina entrambi i documenti, perché ciascuno dei due può riempire lo slot: «Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it.» (Associa una Feature con quel nome, nell’Aggregate o nella Release, sul componente o a un livello superiore.)
L’editor legge lo stesso posizionamento: un rilievo posizionato nella Release viene mostrato sul documento della Release, sulla chiave che lo ha scritto, e per nulla su quello dell’Aggregate; uno posizionato nel documento di un modulo importato dall’Aggregate viene mostrato allo stesso modo sul documento di quel modulo.
Forma dell’output
Una diagnostica stampata si apre con l’intestazione tra parentesi quadre e il puntatore alla sorgente, e pone il messaggio su una propria riga rientrata:
[CATEGORY SHORTCODE] <source> <message>L’intestazione contiene due token, che rispondono a domande diverse. La categoria è una di quelle elencate sopra e dice quale ambito esaminare. Il codice breve è la lettera E seguita da quattro cifre, e nomina la condizione esatta che ha arrestato la build: citalo in una segnalazione, digitalo in una ricerca o risolvilo nella tabella di tutte le condizioni in sentinels.md. Nessuno dei due si ricava dall’altro, ed è per questo che vengono stampati entrambi — e dove una categoria copre più di un rimedio, come fa [TRUST_ERROR], è il codice breve a dirti quale hai incontrato.
Un codice sollevato da un plugin è qualificato dal plugin che lo ha sollevato
Ogni codice breve nomina una condizione che Aggrega dichiara, e due condizioni non ne condividono mai uno: una condizione dichiarata con un numero già detenuto da un’altra condizione viene rifiutata prima che il compilatore legga qualsiasi input. Un plugin non assegna codici propri. Quando segnala un errore, nomina una delle condizioni che Aggrega dichiara — una delle poche condizioni generali che descrivono come un plugin ha fallito, o una più specifica dove ce n’è una adatta — e fornisce la frase che dice cosa è effettivamente successo. Quindi due plugin possono segnalare lo stesso codice breve, e quando lo fanno stanno segnalando la stessa condizione.
Ciò che il codice non può dire è quale plugin ha incontrato la condizione, e un’intestazione che segnala una condizione sollevata da un plugin riporta l’identità del plugin subito prima del codice:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>Il codice breve è sempre il segmento finale — la lettera E seguita da quattro cifre, dopo l’ultimo /. L’identità di un plugin contiene separatori propri, e può contenere una versione, quindi leggere dalla fine anziché dal primo / è ciò che rende il codice recuperabile da qualsiasi intestazione. Tutto ciò che precede quel segmento finale è il plugin.
Il segmento finale si risolve come qualsiasi altro codice breve, qualunque sia il plugin che lo ha sollevato: la tabella di tutte le condizioni in sentinels.md lo elenca, e aggrega explain lo risolve. Cita solo il segmento finale — il qualificatore dice quale plugin ha incontrato la condizione, non di quale condizione si tratta. Un plugin che nomina un codice che Aggrega non dichiara — un numero che nessuna condizione detiene, o uno ritirato — non vede stampato quel codice: la build si arresta su E0293, qualificato da quel plugin, e il suo messaggio cita il codice offerto dal plugin, nomina quelle condizioni generali e conserva la frase del plugin stesso.
Un’intestazione che stampa un codice breve senza qualificatore segnala una condizione sollevata da Aggrega stessa, il che include il caso in cui un plugin ha fallito senza nominare alcuna condizione propria. In quel caso è la condizione generica del compilatore per il fallimento di un plugin ad aver arrestato la build, e il messaggio del plugin riporta il dettaglio.
Ciascuno dei due token può mancare, e quello assente viene omesso
Nulla prende mai il posto di un token che la diagnostica non ha — nessun segnaposto, nessuna parentesi vuota. Un’intestazione può risultare ridotta in tre modi, e ciascuno ti dice qualcosa:
- Nessun codice breve. L’errore non nomina alcuna condizione propria di Aggrega — molto spesso si tratta di un guasto segnalato da una libreria che il compilatore incapsula. L’intestazione stampa solo la categoria, così sai comunque quale superficie esaminare.
- Nessuna categoria. L’errore non ha alcun ambito verso cui indirizzarti, quindi non se ne indovina nessuno. L’intestazione stampa solo il codice breve, ed è il codice che risolvi. Due situazioni lo producono, e si leggono allo stesso modo perché ai tuoi fini sono uguali — nessuna delle due ti dice dove guardare, e il codice ti dice cosa è successo. Una è un difetto del compilatore stesso, in cui il messaggio lo dice e ti chiede di segnalarlo; il caso che si presenta è quello in cui le viste del compilatore sul catalogo non concordano tra loro. L’altra è un errore che nomina una condizione ma non ha mai attraversato una superficie che lo classifichi sotto un ambito, che è la forma consueta di un rifiuto sollevato al confine del comando. Una categoria non viene mai inventata per colmare la lacuna, ed è questo il senso dell’omissione, non un suo limite: la categoria risponde a «quale ambito esamino», e una risposta fornita dove la domanda non ne ha una non è una risposta prudente ma una sbagliata, su cui si agisce per prima. Va anche detto che l’inferenza inversa non regge: un’intestazione che ha una categoria non punta sempre a qualcosa che hai scritto tu, perché
[FETCH_ERROR],[POLICY_ERROR]e[TRUST_ERROR]nominano ciascuno un ambito anziché una superficie di authoring. - Nessuno dei due. Le parentesi quadre sono omesse del tutto e la diagnostica coincide con il suo messaggio. Si tratta di un errore che non nomina alcuna condizione propria di Aggrega e non ha alcun ambito verso cui indirizzarti: un comando che rifiuta i propri argomenti, un file che non riesce a leggere, un annullamento, o un guasto segnalato da una libreria che il compilatore incapsula senza alcuna condizione nostra sottostante. Non c’è nulla da risolvere in
sentinels.md, e il messaggio è tutto ciò che l’errore ha da dire.
Lo stesso errore ridotto a una riga, la forma adatta all’output di log anziché a un terminale, riporta la categoria e omette il codice breve:
[CATEGORY] <source>: <message>Una categoria assente dall’intestazione è assente anche qui, parentesi quadre comprese, quindi questa riga non è mai [] <source>: <message>. La forma su una riga viene reincapsulata nei frame che la racchiudono mentre l’errore risale, quindi un tag vuoto verrebbe trasportato in ognuno di essi.
La sorgente è un puntatore strutturato — tipicamente <file>:<line>:<column> quando è disponibile una posizione YAML, oppure un identificatore logico (il nome dell’entità di catalogo, il nome della Release, il percorso del confine) quando non si applica alcuna posizione nel file. Una terza forma, <file> at <key>, compare quando il puntatore conosce sia il documento sia la chiave di authoring al suo interno, ma nessuna posizione in byte: il file è ciò che apri, e la chiave è ciò da guardare una volta aperto. Il messaggio è la diagnostica specifica della superficie.
Un fallimento che riguarda una singola istanza della tua build — un componente, un componente fornito da un modulo o un modulo stesso — nomina quell’istanza dopo la posizione, come (instance <name>), per cui aggregate.yaml (instance shop) è l’Aggregate che dichiara il modulo shop. Dove il fallimento non ha alcun documento a cui puntare, l’istanza compare da sola come instance <name>: un provider che fallisce mentre renderizza il componente adminer stampa [TRANSLATION_ERROR E0082] instance adminer, e le righe sottostanti riportano il resto del fallimento, compreso qualsiasi documento che esso nomina. Il nome è quello con cui l’Aggregate dichiara il componente; un componente fornito da un modulo è nominato dal suo percorso attraverso il modulo, come shop.cart. Un’istanza non viene mai stampata dove va un file, quindi ciò con cui inizia la sorgente è un documento che puoi aprire, oppure uno degli identificatori logici descritti sopra.
Una regola valutata sul grafo completato segnala in quella terza forma, e la chiave è ciò che distingue due rilievi quando il solo messaggio non può farlo. Una regola di questo tipo nomina il tipo di componente dichiarante anziché l’istanza, quindi due componenti dello stesso tipo che violano la stessa regola riportano lo stesso messaggio sullo stesso file:
[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 chiave è l’unica parte che differisce, ed è ciò che indica quale dei due componenti modificare. Entrambi i rilievi riportano lo stesso codice breve perché sono la stessa condizione, incontrata due volte — il codice breve nomina la regola, e la chiave nomina l’occorrenza.
Due ulteriori righe appartengono alla forma, per un errore che porta il contesto per riempirle — l’espressione di template che è fallita, e un’istantanea dei pilastri disponibili nel punto in cui è fallita:
[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 riga expression: riporta l’estratto di template che ha innescato l’errore. Il blocco active pillars: elenca le chiavi di pilastro di primo livello disponibili nel punto dell’errore, così gli autori vedono cosa era interrogabile. Entrambi vengono omessi quando l’errore non porta né l’uno né l’altro.
Frame di contesto annidati
Un errore attraversa spesso più di una superficie nel suo percorso verso la CLI: una fase di caricamento incapsula l’errore specifico dell’entità, che a sua volta incapsula una sentinella che spiega la regola. Ogni frame categorizzato di una tale catena viene reso — il più esterno come intestazione nella forma vista sopra, ciascun frame annidato come una continuazione caused by: rientrata con il proprio tag di categoria, il proprio puntatore alla sorgente e il proprio messaggio. Il frame più interno che punta a un file è sempre visibile:
[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")Solo l’intestazione riporta un codice breve, e le continuazioni riportano solo la propria categoria. La condizione è nominata una volta, nel punto in cui il lettore incontra l’errore; i frame sotto un marcatore caused by: sono lo stesso errore visto più dall’interno, quindi ripeterne l’identificatore su ciascuno aggiungerebbe righe senza aggiungere fatti. Un blocco note: non è una continuazione e non segue questa regola — riporta le condizioni di altri documenti anziché la stessa vista più dall’interno; la sezione seguente se ne occupa. Il codice che l’intestazione stampa è quello che la catena nomina — qui la regola in fondo — quindi un frame di contesto di fase in cima identifica comunque la condizione sottostante.
Leggendo dall’alto verso il basso: la fase che è fallita, poi l’entità (con il percorso del suo file) che l’ha causata, poi la regola violata. Un frame annidato che non aggiunge nulla rispetto al suo genitore (stessa categoria, stessa sorgente, un messaggio che il genitore contiene già) viene deduplicato anziché ripetuto, e una spiegazione terminale viene resa solo quando i frame sopra di essa non ne riportano già il testo.
Una catena diventa più profonda ogni volta che un errore attraversa più superfici nel suo percorso verso l’esterno, e la regola vale a ogni profondità. Un template rifiutato all’interno del Workload sintetizzato di una Recipe ne attraversa tre — il nodo in fase di rendering, la superficie di template della Recipe e il template stesso:
[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)Leggila dall’alto verso il basso come prima, e nota tre cose che la profondità aggiuntiva rende visibili. Il codice breve compare una sola volta, nell’intestazione, per quante continuazioni la seguano. Il frame più interno è dove si trova la frase propria della condizione, quindi la riga più profonda è sia quella su cui fare corrispondenza sia quella che dice cosa cambiare. E un frame senza puntatore alla sorgente stampa solo la propria categoria: il frame centrale qui sopra nomina nel suo messaggio la superficie su cui è fallito, perché quella superficie è un template anziché un file e non ha una posizione a cui puntare.
Quando l’errore si dirama sotto un frame — una fase che ha raccolto diverse violazioni indipendenti prima di arrestarsi — la continuazione riporta un conteggio, e ogni errore raccolto viene reso sotto di essa, separato dalla stessa linea --- usata dalle catene multi-errore più sotto:
[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 itAnche gli errori raccolti sotto il conteggio sono continuazioni, quindi nessuno di essi ripete il codice breve dell’intestazione — ed è questo che impedisce a una diramazione di una dozzina di violazioni di stampare lo stesso identificatore una dozzina di volte.
Ovunque vale un’unica grammatica dei separatori: --- tra errori fratelli, caused by: tra frame di contesto annidati.
Un file di catalogo rifiutato e l’errore che spiega
Il caricamento di un catalogo per risolvere ciò da cui dipende una Release è tollerante di proposito: un file che non può essere letto, o un documento Aggrega che non può essere analizzato o indicizzato, viene rifiutato e registrato anziché interrompere l’intero caricamento. È questo che impedisce a un’entità difettosa che la tua Release non tocca mai di far fallire una build non correlata.
La conseguenza è che un file rifiutato scompare silenziosamente dal catalogo — e se la tua Release lo raggiunge davvero, ciò che fallisce è il tentativo di risolvere un riferimento a ciò che quel file dichiarava. Quell’errore è una conseguenza del rifiuto anziché il rifiuto stesso, quindi il resoconto mette i due in ordine causale ovunque possa nominare il rifiuto con esattezza:
[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"Il rifiuto viene per primo, con la propria categoria e il proprio codice breve, perché nomina la cosa su cui puoi agire: la correzione è un implements: mancante in una Recipe, non qualcosa che riguardi il modo in cui un riferimento viene cercato in un registry. L’errore di risoluzione viene comunque riportato, sotto di esso, perché è ciò che dice perché quel documento serviva.
Un rifiuto viene per primo solo quando esattamente un file rifiutato dichiara l’identità che il riferimento fallito nomina. La corrispondenza avviene sull’identità che ogni documento dichiara per sé — il suo tipo, il suo nome, la sua versione e, per una ricetta, lo spec.capability che la delimita — quindi un file rifiutato che dichiara ciò che il riferimento chiede è il file in cui quel riferimento si sarebbe risolto. Ne seguono due conseguenze. Un riferimento che indica un intervallo di versioni anziché una versione non nomina un singolo documento, quindi non ne isola nessuno. E un documento troppo malformato perché la sua intestazione possa essere letta non dichiara alcuna identità, quindi non viene mai indicato come causa di qualcosa.
Dove nessun file rifiutato dichiara quell’identità, o più di uno la dichiara, il resoconto è quello che sarebbe senza alcun registro dei rifiuti: l’errore viene per primo, e ogni rifiuto è elencato sotto di esso perché tu lo valuti. Indicare il file sbagliato come causa sarebbe peggio che non indicarne nessuno, perché agiresti di conseguenza.
[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 schemaSu quella seconda forma vale la pena sapere alcune cose, perché ognuna risponde a una domanda che il blocco altrimenti solleverebbe.
L’intestazione nomina l’errore, non un rifiuto. Il codice breve in cima è quello sollevato dall’errore di risoluzione, perché è quell’errore a venire per primo qui — nessun file rifiutato è stato isolato, quindi nessuno di essi apre la riga. Non ha alcuna categoria accanto perché nulla su questo percorso ha classificato l’errore sotto un ambito. L’intestazione di ciascun rifiuto si trova nella sua voce, più sotto, ed è lì che la leggi.
Ogni rifiuto è elencato, non solo quello che contava. Arrivare a questa forma significa che il registro non ha potuto isolarne uno, quindi la nota enuncia la distinzione invece di tirare a indovinare: un rifiuto fuori dalla chiusura di questa Release è tollerato e non può essere ciò che è fallito, il che lascia un rifiuto che nomina qualcosa che la Release raggiunge come l’unica voce che lo spiega. Leggi le voci alla luce di ciò che la tua Release usa effettivamente.
Ogni voce riporta la propria intestazione tra parentesi quadre — la propria categoria e il proprio codice breve. Questo è l’unico punto in cui un codice breve compare sotto l’intestazione della diagnostica, e non è un’eccezione alla regola delle continuazioni vista sopra ma una sua conseguenza: una voce sotto note: non è lo stesso errore visto più dall’interno, è una condizione diversa sollevata da un documento diverso. Nominarne la condizione è ciò che ti permette di cercare il rifiuto e correggere il file, che è l’azione che il blocco esiste per consentire.
Un file rifiutato la cui intestazione era troppo malformata per recuperare l’identità che dichiara viene elencato solo per percorso. È la lettura onesta di un documento in cui nulla ha potuto sbirciare, e il percorso basta comunque per aprire il file. Un file troppo malformato perché se ne possa leggere persino il tipo — uno che non viene analizzato come YAML, per esempio — viene elencato in questo modo quando dichiara un apiVersion di Aggrega, tramite una riga che inizia, senza rientro, con apiVersion: e un valore che comincia con aggrega.ai/, con il motivo indicato dal parser stesso: la riga, e ciò che il parser si aspettava lì. Un file YAML che dichiara un altro apiVersion, o nessuno, non è un documento Aggrega — il template di un chart, per esempio, o un file di configurazione tenuto accanto alle entità — quindi non viene mai elencato, per quanto malformato.
Un file che dichiara un tipo che nessun catalogo contiene viene nominato solo dove spiega l’errore. Un documento che dichiara un apiVersion di Aggrega e un kind che nessun catalogo contiene — un Componnent scritto male, per esempio — viene ignorato da ogni caricamento, quindi non è un rifiuto e non è elencato tra questi. Dove il riferimento fallito chiede il nome che quel file dichiara, e la versione dove il riferimento ne indica una, il resoconto lo nomina in una nota propria sotto l’errore, qualunque sia il tipo con cui il riferimento è stato raccolto — su ogni superficie elencata più sotto, e su aggrega build sia che legga un lockfile esistente sia che ne riempia prima uno:
[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’errore continua a venire per primo: il tipo che il file dichiara non nomina alcuna identità, quindi il file non viene mai isolato come il rifiuto con cui si apre il resoconto. La spiegazione di dove vengono lette le entità locali è esclusa da quel resoconto, perché il file si trova già dove il catalogo legge e spostarlo non servirebbe. Un file di un tipo che nessun catalogo contiene e che dichiara un altro nome non spiega nulla di questo errore e non viene menzionato. aggrega serve, i cui messaggi stanno su una riga, riporta la stessa nota su quella riga — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: seguito dal rifiuto del file — e non elenca mai un file del genere tra i file saltati al caricamento; lo strumento describe di aggrega mcp, interrogato su un nome nei termini di una Release, lo nomina anch’esso al posto di quella spiegazione. aggrega validate e aggrega lint sull’intero catalogo segnalano ogni file del genere, che qualcosa lo raggiunga o no — vedi fatal-halts.md §«A catalog document declares a kind a catalog does not hold (Un documento di catalogo dichiara un tipo che un catalogo non contiene)».
Qualunque forma tu ottenga, l’errore mantiene la propria identità. La nota viene aggiunta all’errore anziché resa al suo posto, e far venire per primo un rifiuto cambia solo ciò che leggi per primo — quindi la condizione sollevata dall’errore resta intatta in entrambi i casi: il suo codice breve si risolve ancora, e uno strumento che fa corrispondenza sulla condizione la trova ancora.
Dove il documento rifiutato è esso stesso ciò che un comando riporta, il rifiuto viene enunciato una sola volta. aggrega inspect <name> carica il catalogo in modo rigoroso, quindi un documento che il caricamento rifiuta lo arresta, e ciò che stampa è il rifiuto di quel documento come una singola diagnostica: l’intestazione con la categoria e il codice breve del rifiuto, il documento come sua sorgente, e sotto ciò che non va nel documento — per una violazione di schema, le chiavi violate con le loro righe e colonne, e il consiglio. Il caricamento che lo ha sollevato è passato per la directory che stava percorrendo e per il passo che ha letto il file, e questi non vengono stampati come frame propri, perché ciascuno nominerebbe di nuovo lo stesso documento senza aggiungere un fatto. aggrega serve, interrogato su ciò a cui un nome si riferisce dove un documento rifiutato dichiara quel nome, risponde con lo stesso rifiuto, con le stesse parole, su una riga, seguito dalla nota che il file è stato saltato al caricamento. Come sopra, la condizione del rifiuto resta riconoscibile in entrambi i casi.
Entrambe le forme ti raggiungono ovunque venga eseguita quella risoluzione. aggrega build, aggrega pull, aggrega validate --release e aggrega inspect --closure le producono in un terminale, come fa aggrega validate su una singola Recipe la cui destinazione implements non viene trovata, e un assistente IA collegato tramite aggrega mcp riceve la stessa spiegazione dagli strumenti build e validate, e il rifiuto iniziale su una sola riga da una lettura catalog:// di un’entità dichiarata da un file rifiutato. La superficie da cui hai chiesto non cambia nulla su quale file ti viene indicato di aprire — a un chiamante che raggiunge aggrega mcp via HTTP viene indicato relativamente alla radice del workspace, e non gliene viene indicato uno fuori dal workspace servito da quel server — e dove un rifiuto viene per primo, il contratto di authoring a cui punta la risposta è quello del tipo che il documento rifiutato dichiara — non del tipo del riferimento che è fallito.
La classe di errori dell’involucro del documento
Ogni documento di entità — entità del catalogo, Aggregates, Manifests, Releases — viene convalidato rispetto allo schema JSON pubblicato del suo tipo nel momento in cui viene caricato, prima dell’analisi tipizzata. Un documento che viola il proprio involucro (una chiave sconosciuta, un campo obbligatorio mancante, un valore della forma sbagliata, un costrutto vietato come values: nella Release) arresta la build in modo esplicito con una diagnostica che nomina prima la condizione, poi il tipo di entità e il file, poi ogni chiave o forma non valida con la riga e la colonna in cui si trova, e infine cosa fare:
[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 schemaLa diagnostica si apre con la condizione, nomina il tipo e il file e si chiude con cosa fare; ogni violazione tra i due porta soltanto line:column, poiché l’intestazione ha già nominato il file. Ogni chiave non valida viene segnalata nella propria posizione anziché nella posizione del blocco che la contiene, così la riga e la colonna puntano alla chiave che devi modificare. Quando la forma della posizione deriva da una definizione riutilizzabile dello schema, la diagnostica nomina quella definizione dopo la parola against — against /$defs/boundary nell’esempio sopra — così è chiaro rispetto a quale contratto è stata misurata la chiave, e la definizione non si legge come un ulteriore passo lungo il percorso di chiavi che hai scritto. Un documento con più violazioni le elenca ciascuna nella propria posizione, in ordine di chiave, e il resoconto si ferma dopo quattro con il conteggio delle restanti.
Due cose meritano di essere conosciute su dove punta una posizione, perché entrambe sono utili anziché sorprendenti:
- Una chiave obbligatoria mancante non ha una posizione propria — per definizione è assente dal documento. La violazione punta invece alla chiave che la racchiude, che è dove va la voce mancante. Quindi
spec.capability: missing required propertypunta aspec:, ed è lì che la aggiungi. - Una chiave il cui nome contiene un punto — ogni etichetta
component.aggrega.ai/…e ogni annotazionefeatures.aggrega.ai/…— viene segnalata nel blocco che la contiene anziché nella voce stessa, poiché i punti si leggono come passi verso l’interno del documento. Una violazione su un’etichetta punta alabels:.
Quando una violazione nomina una chiave che non compare da nessuna parte nel documento — per esempio un intero blocco metadata: omesso — la posizione viene omessa anziché indovinata, e la violazione si legge come il solo percorso della chiave seguito dal messaggio. Una posizione di cui dovresti diffidare è peggio di nessuna.
La categoria segue la superficie di authoring: [CATALOG_ERROR] per le entità del catalogo, [DEVELOPER_ERROR] per gli Aggregates, [OPS_ERROR] per Releases e Manifests. Lo stesso controllo viene eseguito su ogni superficie che carica entità — aggrega build, aggrega lint, aggrega validate e la diagnostica dell’editor pubblicata da aggrega serve — così una chiave estranea o scritta male viene rifiutata ovunque il documento venga letto per la prima volta, invece di essere scartata silenziosamente. Ciascuna di queste superfici risolve la posizione allo stesso modo, quindi puntano alla stessa chiave, e ciascuna legge la frase della condizione dalla condizione stessa: la riga che il tuo editor sottolinea è la riga che il terminale nomina, e la frase con cui si apre la voce dell’editor è la frase con cui si apre il terminale. Ciò che le due superfici non condividono è il messaggio completo, ed è voluto — il terminale raggruppa ogni rilievo sotto un’unica intestazione e si chiude con il consiglio per il percorso, mentre l’editor emette una voce per ciascun rilievo, posizionata sulla propria chiave, senza ripetere né il file a cui è già collegata né un consiglio che altrimenti ripeterebbe a ogni sottolineatura. Quindi la parte che converge è quella da cui riconosci la condizione.
Catene di errori multipli
Quando una singola compilazione rileva più violazioni indipendenti (più comunemente durante l’analisi statica, in cui ogni violazione di selettore e di appliesTo viene raccolta prima che una qualsiasi di esse arresti la build), gli errori vengono uniti in un’unica catena. La CLI percorre la catena e presenta ogni sotto-errore in modo indipendente, separandoli con una riga orizzontale:
[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.Il separatore --- è letterale — chi legge e gli strumenti a valle possono dividere su di esso per enumerare gli errori uniti. Ogni sotto-errore è un fallimento a sé stante anziché un dettaglio di quello adiacente, quindi ciascuno ha un’intestazione propria: la propria categoria e il proprio codice breve, ciascuno dove esiste, come descrive la sezione sui token assenti. Due violazioni di una stessa regola riportano lo stesso codice breve, come sopra; due violazioni di regole diverse ne riportano di diversi.
Leggere un errore dall’inizio alla fine
Nella maggior parte dei contesti di authoring, il prefisso di categoria e il puntatore alla sorgente identificano insieme cosa correggere:
| Categoria | Dove si trova la correzione | Superfici di esempio |
|---|---|---|
[DEVELOPER_ERROR] | YAML dell’Aggregate | Violazioni di selettore / appliesTo su ciò che l’Aggregate ha scritto; mancata corrispondenza del socket uses lato Aggregate; arresti del resolver sull’authoring dello sviluppatore. |
[OPS_ERROR] | YAML della Release / YAML del Manifest | Il template di percorso del confine fa riferimento a un campo non supportato; subDirectory causa una collisione di percorsi; arresti del resolver sull’authoring della Release; una connessione che la Release cabla, o un’associazione che essa compila su una connessione, rifiutati dalle regole del socket o dello slot; una Feature che solo la Release collega, a un componente o a un confine, rifiutata dalle regole della Feature o dello slot; un mapping o un binding di annotazione di un Manifest viene rifiutato. |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Regole di forma della Recipe; il template della FeatureRecipe fa riferimento a un campo solo per componente con executionScope: boundary; il controllo incrociato di featuresSchema del Workload fallisce. |
[TRANSLATION_ERROR] | Workload / output di valuesMapping / overlay della sorgente | Risoluzione della porta delle probe di Helm; collisione dei nomi dei servizi compose tra confini; due contributori compose che dichiarano lo stesso nome di volume o di config di primo livello con corpi in conflitto; mancata corrispondenza del nome del chart sull’umbrella helm-chart. |
[FETCH_ERROR] | Acquisizione da registry / sorgente remota (operativa, non di authoring) | Artefatto non trovato nel registry; autenticazione richiesta; rete irraggiungibile; digest in cache non corrispondente rispetto al lockfile. Correzione: autenticati, ripristina la connettività oppure aggrega pull --upgrade --release <release>. |
[POLICY_ERROR] | Plugin di policy (regola di governance) | Un plugin di policy collegato a un ruolo di verdetto di governance ha rifiutato la build assemblata in base a una regola che applica. Correzione: soddisfa la policy applicata oppure riconsidera l’associazione. |
[TRUST_ERROR] | Configurazione di trust, o la firma dell’artefatto stesso (un ambito, non una superficie di authoring) | Una policy di trust o una radice di trust fissata che non è leggibile; una policy keyless che non dichiara alcuna identità attendibile; una policy di firma che richiede una firma per il tipo in pubblicazione; un gate di associazione di verdetto registrato che la configurazione non associa più. Oppure: una firma che non si verifica; un artefatto che non ne porta nessuna dove una è richiesta; un firmatario non attendibile; un plugin la cui identità attendibile registrata non corrisponde più. Correzione: correggi la configurazione o il record di trust versionato, oppure decidi in merito all’artefatto — il codice breve indica quale. |
I prefissi di contesto per provider (helm: node "<id>": ..., compose: node "<id>": ...) compaiono nella parte del messaggio degli output [TRANSLATION_ERROR] e [CATALOG_ERROR] per localizzare il provider che fallisce quando è in gioco più di un provider.
Errori nativi delle librerie
Gli errori che hanno origine all’interno di una libreria sottostante (errori di caricamento dei chart dell’SDK di Helm, errori del parser YAML di docker-compose, errori di I/O sui file dovuti a un percorso sorgente mancante) vengono racchiusi con il prefisso di contesto per provider e compaiono sotto [TRANSLATION_ERROR] o [CATALOG_ERROR] a seconda che si siano verificati nella sintesi o nel caricamento del contenuto del catalogo. Il messaggio della libreria racchiuso conserva alla lettera la diagnostica dello strumento originale, così gli autori possono confrontarla con la documentazione dello strumento stesso.
Riferimenti incrociati
fatal-halts.md— catalogo, errore per errore, di ogni arresto fatale con il messaggio previsto e come correggerlo.warnings.md— avvisi non fatali che il compilatore emette.vocabulary/validation-surface.md— i quattro livelli di convalida dello schema e come interagiscono le forme dei loro errori.