Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Disciplina de traducción de errores

La canalización de compilación de Aggrega emite errores desde muchas superficies — validadores de esquema, el resolvedor, el constructor del IR, los proveedores, el motor de plantillas de Go y las bibliotecas YAML / Helm / docker-compose subyacentes que envuelven los proveedores. Los errores que llegan hasta la CLI comienzan con un encabezado entre corchetes que nombra hasta dos cosas — una categoría, que indica qué ámbito revisar (para la mayoría de los valores, la superficie de autoría responsable), y el código corto de la condición que detuvo la compilación — seguido de un puntero al origen y de un mensaje. Cuando fue un plugin quien generó la condición, el código se califica con el plugin que la generó, porque más de un plugin puede notificar la misma condición. Esta página documenta la forma de esa salida para que los autores interpreten directamente los mensajes de error.

Para el catálogo de errores uno por uno (cada detención fatal con indicaciones para corregirla), consulta fatal-halts.md. Para las cuatro capas de validación de esquemas y cómo interactúan las formas de sus errores, consulta vocabulary/validation-surface.md.

Las categorías de error

Una etiqueta de categoría indica qué ámbito revisar. La mayoría nombra la superficie de autoría donde está la corrección; las demás nombran un ámbito que no es un error de autoría de nadie — la adquisición de un artefacto, un veredicto de gobernanza, o la confianza y la firma — y el código corto junto a la categoría en el encabezado es lo que identifica la condición concreta en todos los casos:

  • [DEVELOPER_ERROR] — el fallo corresponde a la autoría del Aggregate. La corrección está en el YAML del Aggregate o en la parte del catálogo escrita por el desarrollador (valores de Component, sockets uses, vinculaciones de Feature). Superficies de ejemplo: detenciones del resolvedor por problemas del lado del Aggregate; infracciones de selector y de appliesTo en lo que escribió el Aggregate.
  • [OPS_ERROR] — el fallo corresponde a los documentos propios del operador, la Release y el Manifest. La corrección está en el YAML de la Release (topología de límites, valores de parámetros, vinculaciones de Feature a nivel de Release) o en el YAML del Manifest (mediante qué Recipe se despliega un tipo, y los enlaces de anotaciones escritos junto a ella). Superficies de ejemplo: validación del esquema de la Release; evaluación de plantillas de rutas de límites; colisiones de subDirectory entre proveedores; rechazos de mapeos y de enlaces de anotaciones del Manifest; una regla que rechaza una conexión que la Release cablea, o una vinculación que rellena en una conexión — el selector de un socket, el selector de un slot, un slot que un socket declara obligatorio; una regla que rechaza una Feature que solo la Release vincula, a un componente o a un límite — el appliesTo de la Feature, el selector de un slot, su esquema declarado.
  • [CATALOG_ERROR] — el fallo corresponde a una entidad del catálogo (Recipe, FeatureRecipe, Component, Feature, Plugin). La corrección está en el contenido del catálogo. Superficies de ejemplo: reglas de forma de la Recipe; comprobaciones cruzadas de featuresSchema del Workload; errores de análisis de plantillas en plantillas escritas en el catálogo.
  • [TRANSLATION_ERROR] — el fallo corresponde a la síntesis del lado del proveedor (un plugin de proveedor que intenta traducir un Workload, la salida de un valuesMapping o una superposición con origen en artefactos nativos del proveedor). La corrección suele estar en la forma services / containers / volumes del Workload, en la salida de la plantilla valuesMapping de la Recipe o en la estructura de la superposición en modo de origen.
  • [FETCH_ERROR] — el fallo corresponde a la obtención de una dependencia fijada desde un registro o un origen remoto, no a ninguna superficie de autoría. La corrección suele ser operativa: autenticarse en el registro (docker login <registry>), restablecer la conectividad o volver a fijar un artefacto que ha divergido o ha sido manipulado (aggrega pull --upgrade --release <release>). Superficies de ejemplo: una entidad de catálogo o un chart que no se encuentra en el registro; autenticación requerida o fallida; red inaccesible; el digest de un artefacto en caché que no coincide con el lockfile. Los errores de obtención incluyen en el mensaje una indicación concreta de cómo corregirlos.
  • [POLICY_ERROR] — la compilación fue rechazada por un plugin de políticas vinculado en un rol de veredicto de gobernanza. No es un fallo de una superficie de autoría: la entrada está bien formada, pero incumple una regla de gobernanza (cumplimiento, FinOps o seguridad) que el plugin impone. La corrección consiste en hacer que lo que escribiste cumpla la política impuesta, o en reconsiderar la vinculación de la política. El mensaje nombra el plugin que rechazó y contiene el mensaje de regla que este proporcionó.
  • [TRUST_ERROR] — la capa de confianza y firma rechazó la operación. Esta categoría nombra un ámbito en lugar de una superficie de autoría, y cubre dos remedios que puedes distinguir por el código corto que la acompaña. Tu configuración de confianza es incorrecta: una política de confianza que no se puede leer, una raíz de confianza fijada que no se puede cargar, una política sin claves que no declara ninguna identidad de confianza, una política de firma que exige una firma para el tipo de artefacto que estás publicando, o un plugin registrado como de confianza para una vinculación de veredicto que tu configuración ya no vincula. Este artefacto no superó la verificación: una firma que no se verifica con el ancla de confianza, un artefacto sin firma donde se requiere una, una firma de un firmante real pero no de confianza, o un plugin cuya identidad de confianza registrada ya no coincide con lo que se resuelve. En el primer caso, la corrección está en tu configuración o en el registro de confianza confirmado en el repositorio; en el segundo, es una decisión sobre el artefacto — restaurar el revisado, o revisar y volver a registrar lo que cambió.

Un hallazgo sobre una vinculación de Feature sigue al documento que la escribió

Una Feature puede vincularse en cualquiera de los dos documentos — el Aggregate vincula una en un componente o en un subsistema, la Release en su entrada para un componente o en un límite — por lo que la categoría de un hallazgo sobre una vinculación se deduce de dónde se escribió la vinculación, no del componente al que llega. El hallazgo se sitúa en la entrada features: que escribió la vinculación, en ese documento, y se clasifica bajo el autor de ese documento: una vinculación que solo hace la Release se notifica en la ruta propia de la Release como [OPS_ERROR], y una que hace el Aggregate, en la ruta del Aggregate como [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.

Cuando ambos documentos escriben una misma vinculación — el Aggregate nombrando su Feature, la Release dimensionándola — un hallazgo sobre la vinculación en su conjunto se sitúa donde se nombra su Feature, es decir, en el Aggregate. Un hallazgo sobre una parte de su configuración se sitúa donde se escribió esa parte: sus values son del desarrollador, en el Aggregate, y su infra del operador, en la Release. Una vinculación producida por la expansión guiada por anotaciones no fue escrita por ninguna entrada features:, así que un hallazgo sobre ella se sitúa en el componente, en el documento que declara el componente, como [DEVELOPER_ERROR].

Un slot obligatorio que queda vacío es el único caso que ningún documento escribió. No hay ninguna vinculación a la que apuntar, así que el hallazgo se queda en el componente en el Aggregate y se clasifica como [DEVELOPER_ERROR], y su remedio nombra ambos documentos, porque cualquiera de los dos puede rellenar el slot: «Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it.» (Vincula una Feature con ese nombre, en el Aggregate o en la Release, en el componente o en un nivel superior.)

El editor lee la misma ubicación: un hallazgo situado en la Release se muestra en el documento de la Release, en la clave que lo escribió, y no aparece en absoluto en el del Aggregate; uno situado en el documento de un módulo que el Aggregate importa se muestra del mismo modo en el documento de ese módulo.

Forma de la salida

Un diagnóstico impreso comienza con el encabezado entre corchetes y el puntero de origen, y coloca el mensaje en su propia línea con sangría:

[CATEGORY SHORTCODE] <source>
<message>

El encabezado lleva dos tokens, y responden a preguntas distintas. La categoría es una de las descritas arriba e indica qué ámbito revisar. El código corto es la letra E seguida de cuatro dígitos, y nombra la condición exacta que detuvo la compilación: cítalo en un informe, escríbelo en una búsqueda o resuélvelo en la tabla de todas las condiciones de sentinels.md. Ninguno se deduce del otro, y por eso se imprimen ambos — y cuando una categoría cubre más de un remedio, como ocurre con [TRUST_ERROR], el código corto es lo que te dice cuál te has encontrado.

Un código generado por un plugin se califica con el plugin que lo generó

Cada código corto nombra una condición que Aggrega declara, y no hay dos condiciones que compartan uno: una condición declarada con un número que ya tiene otra condición se rechaza antes de que el compilador lea ninguna entrada. Un plugin no asigna códigos propios. Cuando informa de un fallo, nombra una de las condiciones que Aggrega declara — una de unas pocas condiciones generales que describen cómo falló un plugin, o una más específica cuando hay una que encaja — y aporta la frase que dice lo que realmente ocurrió. Así que dos plugins pueden informar del mismo código corto, y cuando lo hacen están informando de la misma condición.

Lo que el código no puede decir es qué plugin se encontró con la condición, y un encabezado que informa de una condición generada por un plugin lleva la identidad del plugin justo antes del código:

[CATEGORY PLUGIN/SHORTCODE] <source>
<message>

El código corto es siempre el segmento final — la letra E seguida de cuatro dígitos, después de la última /. La identidad de un plugin lleva sus propios separadores, y puede llevar una versión, así que leer desde el final en lugar de desde la primera / es lo que permite recuperar el código de cualquier encabezado. Todo lo que precede a ese segmento final es el plugin.

El segmento final se resuelve como cualquier otro código corto, sea cual sea el plugin que lo generó: la tabla de todas las condiciones de sentinels.md lo incluye, y aggrega explain lo resuelve. Cita solo el segmento final — el calificador dice qué plugin se encontró con la condición, no qué condición es. Un plugin que nombra un código que Aggrega no declara — un número que ninguna condición tiene, o uno retirado — no consigue que ese código se imprima: la compilación se detiene en E0293, calificado por ese plugin, y su mensaje cita el código que ofreció el plugin, nombra esas condiciones generales y conserva la frase propia del plugin.

Un encabezado que imprime un código corto sin calificar informa de una condición que generó el propio Aggrega, lo que incluye el caso en que un plugin falló sin nombrar ninguna condición propia. En ese caso, lo que detuvo la compilación es la condición genérica de fallo de plugin del compilador, y el mensaje del plugin aporta el detalle.

Cualquiera de los dos tokens puede faltar, y el que falta se omite

Nada ocupa nunca el lugar de un token que el diagnóstico no tiene — ningún marcador de posición, ningún corchete vacío. Hay tres formas en que un encabezado puede quedar reducido, y cada una te dice algo:

  • Sin código corto. El fallo no nombra ninguna condición propia de Aggrega — con mayor frecuencia, se trata de un error notificado por una biblioteca que el compilador envuelve. El encabezado imprime solo la categoría, así que sigues sabiendo qué superficie revisar.
  • Sin categoría. El fallo no tiene ningún ámbito al que remitirte, así que no se adivina ninguno. El encabezado imprime solo el código corto, y el código es lo que resuelves. Dos situaciones lo producen, y se leen igual porque, a tus efectos, son iguales — ninguna te dice dónde mirar, y el código te dice qué ocurrió. Una es un defecto del propio compilador, en el que el mensaje lo dice y te pide que lo notifiques; el caso que se presenta es que las propias vistas del compilador sobre el catálogo discrepan entre sí. La otra es un fallo que nombra una condición pero nunca cruzó una superficie que lo clasifique bajo un ámbito, que es la forma habitual de un rechazo generado en el límite del comando. Nunca se inventa una categoría para llenar el hueco, y ese es el propósito de la omisión, no una limitación suya: la categoría responde a «qué ámbito reviso», y una respuesta dada donde la pregunta no la tiene no es una respuesta prudente, sino una errónea sobre la que se actúa primero. También conviene decir que la inferencia inversa no se sostiene: un encabezado que sí lleva una categoría no siempre apunta a algo que tú escribiste, porque [FETCH_ERROR], [POLICY_ERROR] y [TRUST_ERROR] nombran cada uno un ámbito y no una superficie de autoría.
  • Ninguno de los dos. Los corchetes se omiten por completo y el diagnóstico es su mensaje. Se trata de un fallo que no nombra ninguna condición propia de Aggrega y no tiene ningún ámbito al que remitirte: un comando que rechaza sus argumentos, un archivo que no puede leer, una cancelación o un error notificado por una biblioteca que el compilador envuelve sin ninguna condición nuestra por debajo. No hay nada que resolver en sentinels.md, y el mensaje es todo lo que el fallo tiene que decir.

El mismo error reducido a una línea, la forma adecuada para la salida de registro en lugar de para un terminal, lleva la categoría y omite el código corto:

[CATEGORY] <source>: <message>

Una categoría ausente del encabezado también está ausente aquí, corchetes incluidos, así que esta línea nunca es [] <source>: <message>. La forma de una línea se vuelve a envolver en los marcos que la contienen a medida que el fallo asciende, así que una etiqueta vacía se arrastraría a cada uno de ellos.

El origen es un puntero estructurado — normalmente <file>:<line>:<column> cuando hay una posición YAML disponible, o un identificador lógico (el nombre de la entidad del catálogo, el nombre de la Release, la ruta del límite) cuando no se aplica ninguna posición de archivo. Una tercera forma, <file> at <key>, aparece cuando el puntero conoce tanto el documento como la clave de autoría que contiene, pero ninguna posición en bytes: el archivo es lo que abres, y la clave es lo que debes mirar una vez abierto. El mensaje es el diagnóstico propio de la superficie.

Un fallo sobre una instancia concreta de tu compilación — un componente, un componente que aporta un módulo, o un módulo en sí — nombra esa instancia después de la posición, como (instance <name>), de modo que aggregate.yaml (instance shop) es el Aggregate que declara el módulo shop. Cuando el fallo no tiene ningún documento al que apuntar, la instancia aparece sola como instance <name>: un provider que falla mientras renderiza el componente adminer imprime [TRANSLATION_ERROR E0082] instance adminer, y las líneas de debajo llevan el resto del fallo, incluido cualquier documento que nombre. El nombre es aquel con el que el Aggregate declara el componente; un componente que aporta un módulo se nombra por su ruta a través del módulo, como shop.cart. Una instancia nunca se imprime donde corresponde un archivo, así que aquello con lo que empieza el origen es un documento que puedes abrir, o uno de los identificadores lógicos anteriores.

Una regla evaluada sobre el grafo terminado informa en esa tercera forma, y la clave es lo que distingue dos hallazgos cuando el mensaje por sí solo no puede. Una regla de este tipo nombra el tipo de componente declarante en lugar de la instancia, así que dos componentes de un mismo tipo que incumplen la misma regla llevan el mismo mensaje sobre el mismo archivo:

[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 clave es la única parte que difiere, y es lo que indica cuál de los dos componentes editar. Ambos hallazgos llevan el mismo código corto porque ambos son la misma condición, encontrada dos veces — el código corto nombra la regla, y la clave nombra la ocurrencia.

Dos líneas más forman parte de la forma, para un fallo que lleva el contexto necesario para rellenarlas — la expresión de plantilla que falló, y una instantánea de los pilares disponibles donde falló:

[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 línea expression: lleva el fragmento de plantilla que provocó el fallo. El bloque active pillars: enumera las claves de pilar de nivel superior disponibles en el punto del fallo, para que los autores vean qué se podía consultar. Ambos se omiten cuando el fallo no lleva ninguno de los dos.

Marcos de contexto anidados

Un error suele cruzar más de una superficie en su camino hacia la CLI: una fase de carga envuelve el fallo específico de la entidad, que a su vez envuelve un centinela que explica la regla. Cada marco categorizado de una cadena así se representa — el más externo como el encabezado con la forma anterior, cada marco anidado como una continuación caused by: con sangría que lleva su propia etiqueta de categoría, su propio puntero de origen y su propio mensaje. El marco más interno que apunta a un archivo siempre es 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")

Solo el encabezado lleva un código corto, y las continuaciones llevan solo su categoría. La condición se nombra una vez, en el punto en que el lector se encuentra con el fallo; los marcos que hay bajo un marcador caused by: son ese mismo fallo visto desde más adentro, así que repetir su identificador en cada uno añadiría líneas sin añadir hechos. Un bloque note: no es una continuación y no sigue esta regla — informa de las condiciones de otros documentos y no de la misma vista desde más adentro; la sección siguiente lo trata. El código que imprime el encabezado es el que nombra la cadena — aquí la regla del fondo —, así que un marco de contexto de fase en la parte superior sigue identificando la condición que hay debajo.

Leyendo de arriba abajo: la fase que falló, luego la entidad (con su ruta de archivo) que lo causó, luego la regla que incumplió. Un marco anidado que no añade nada respecto a su padre (misma categoría, mismo origen, un mensaje que el padre ya contiene) se deduplica en lugar de repetirse, y una explicación terminal solo se representa cuando los marcos superiores no llevan ya su texto.

Una cadena es más profunda siempre que un fallo cruza más superficies en su salida, y la regla se cumple a cualquier profundidad. Una plantilla rechazada dentro del Workload sintetizado de una Recipe cruza tres — el nodo que se está renderizando, la superficie de plantillas de la Recipe y la propia plantilla:

[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)

Léela de arriba abajo como antes, y fíjate en tres cosas que la profundidad adicional hace visibles. El código corto aparece una vez, en el encabezado, por muchas continuaciones que le sigan. El marco más interno es donde está la frase propia de la condición, así que la línea más profunda es a la vez la que hay que usar para la coincidencia y la que dice qué cambiar. Y un marco sin puntero de origen imprime solo su categoría: el marco intermedio de arriba nombra en su mensaje la superficie en la que falló, porque esa superficie es una plantilla y no un archivo, y no tiene ninguna posición a la que apuntar.

Cuando el fallo se bifurca bajo un marco — una fase que reunió varias infracciones independientes antes de detenerse —, la continuación lleva un recuento, y cada fallo reunido se representa debajo, separado por la misma línea --- que usan las cadenas de múltiples errores más abajo:

[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 it

Los fallos reunidos bajo el recuento también son continuaciones, así que ninguno repite el código corto del encabezado — que es lo que evita que una bifurcación de una docena de infracciones imprima el mismo identificador una docena de veces.

Se aplica una única gramática de separadores en todo momento: --- entre fallos hermanos, caused by: entre marcos de contexto anidados.

Un archivo de catálogo rechazado y el fallo que explica

La carga de un catálogo para resolver aquello de lo que depende una Release es tolerante a propósito: un archivo que no se puede leer, o un documento de Aggrega que no se puede analizar ni indexar, se rechaza y se registra en lugar de abortar toda la carga. Eso es lo que impide que una entidad defectuosa que tu Release nunca toca haga fallar una compilación no relacionada.

La consecuencia es que un archivo rechazado desaparece del catálogo sin aviso — y si tu Release sí llega a él, lo que falla es el intento de resolver una referencia a lo que ese archivo declaraba. Ese fallo es una consecuencia del rechazo y no el rechazo en sí, así que el informe pone ambos en orden causal siempre que puede nombrar el rechazo con exactitud:

[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"

El rechazo va primero, con su propia categoría y su propio código corto, porque nombra aquello sobre lo que puedes actuar: la corrección es un implements: que falta en una Recipe, y no algo relacionado con cómo se busca una referencia en un registro. El fallo de resolución se sigue notificando, debajo, porque es lo que dice por qué se necesitaba ese documento.

Un rechazo va primero solo cuando exactamente un archivo rechazado declara la identidad que nombra la referencia que falla. La coincidencia se hace sobre la identidad que cada documento declara para sí mismo — su tipo, su nombre, su versión y, para una receta, la spec.capability que la delimita —, así que un archivo rechazado que declara lo que pide la referencia es el archivo al que esa referencia se habría resuelto. De ello se siguen dos consecuencias. Una referencia que indica un rango de versiones en lugar de una versión no nombra un único documento, así que no señala nada. Y un documento demasiado mal formado para que se pueda leer su encabezado no declara ninguna identidad, así que nunca se nombra como causa de nada.

Cuando ningún archivo rechazado declara esa identidad, o la declara más de uno, el informe es el que sería sin registro de rechazos: el fallo va primero, y cada rechazo se enumera debajo para que lo sopeses. Nombrar el archivo equivocado como causa sería peor que no nombrar ninguno, porque actuarías en consecuencia.

[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 schema

Conviene saber algunas cosas sobre esa segunda forma, porque cada una responde a una pregunta que el bloque plantearía de otro modo.

El encabezado nombra el fallo, no un rechazo. El código corto de arriba es el que generó el fallo de resolución, porque ese fallo es lo que va primero aquí — no se señaló ningún archivo rechazado, así que ninguno encabeza la línea. No lleva ninguna categoría al lado porque nada en este camino clasificó el fallo bajo un ámbito. El encabezado propio de cada rechazo está en su propia entrada debajo, que es donde lo lees.

Se enumera cada rechazo, no solo el que importaba. Llegar a esta forma significa que el registro no pudo señalar uno solo, así que la nota expone la distinción en lugar de adivinar: un rechazo fuera de la clausura de esta Release se tolera y no puede ser lo que falló, lo que deja un rechazo que nombra algo que la Release alcanza como la única entrada que explica el fallo. Lee las entradas a la luz de lo que tu Release usa realmente.

Cada entrada lleva su propio encabezado entre corchetes — su propia categoría y su propio código corto. Este es el único lugar en que un código corto aparece por debajo del encabezado del diagnóstico, y no es una excepción a la regla de las continuaciones anterior, sino una consecuencia de ella: una entrada bajo note: no es el mismo fallo visto desde más adentro, es una condición distinta generada por un documento distinto. Nombrar su condición es lo que te permite buscar el rechazo y corregir el archivo, que es la acción que el bloque existe para hacer posible.

Un archivo rechazado cuyo encabezado estaba demasiado mal formado para recuperar la identidad que declara se enumera solo por su ruta. Es la lectura honesta de un documento en el que nada pudo asomarse, y la ruta sigue bastando para abrir el archivo. Un archivo demasiado mal formado para que se pueda leer siquiera su tipo — uno que no se analiza como YAML, por ejemplo — se enumera de esta forma cuando declara una apiVersion de Aggrega, mediante una línea que empieza, sin sangría, por apiVersion: y un valor que comienza por aggrega.ai/, con el motivo que da el propio analizador: la línea, y lo que el analizador esperaba allí. Un archivo YAML que declara otra apiVersion, o ninguna, no es un documento de Aggrega — la plantilla de un chart, por ejemplo, o un archivo de configuración guardado junto a las entidades —, así que nunca se enumera, por mal formado que esté.

Un archivo que declara un tipo que ningún catálogo contiene solo se nombra donde explica el fallo. Un documento que declara una apiVersion de Aggrega y un kind que ningún catálogo contiene — un Componnent mal escrito, por ejemplo — se omite en cada carga, así que no es un rechazo y no se enumera entre ellos. Cuando la referencia que falla pide el nombre que declara ese archivo, y la versión cuando la referencia indica una, el informe lo nombra en una nota propia debajo del fallo, sea cual sea el tipo con el que se recogió la referencia — en cada superficie enumerada más abajo, y en aggrega build, tanto si lee un lockfile existente como si primero rellena 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 directories

El fallo sigue yendo primero: el tipo que declara el archivo no nombra ninguna identidad, así que el archivo nunca se señala como el rechazo con el que empieza el informe. La explicación de dónde se leen las entidades locales se deja fuera de ese informe, porque el archivo ya está donde lee el catálogo y moverlo no ayudaría. Un archivo de un tipo que ningún catálogo contiene y que declara algún otro nombre no explica nada de este fallo y no se menciona. aggrega serve, cuyos mensajes ocupan una línea, lleva la misma nota en esa línea — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: seguida del rechazo del archivo — y nunca enumera ese archivo entre los archivos omitidos en la carga; la herramienta describe de aggrega mcp, cuando se le pide un nombre en los términos de una Release, también lo nombra en lugar de esa explicación. aggrega validate y aggrega lint sobre el catálogo completo informan de cada uno de esos archivos, lo alcance algo o no — consulta fatal-halts.md §«A catalog document declares a kind a catalog does not hold (Un documento de catálogo declara un tipo que un catálogo no contiene)».

Sea cual sea la forma que obtengas, el fallo conserva su propia identidad. La nota se añade al fallo en lugar de representarse por encima de él, y poner primero un rechazo solo cambia lo que lees primero — así que la condición que generó el fallo permanece intacta en ambos casos: su código corto se sigue resolviendo, y una herramienta que busca coincidencias con la condición sigue encontrándola.

Cuando el documento rechazado es en sí lo que notifica un comando, el rechazo se expone una sola vez. aggrega inspect <name> carga el catálogo de forma estricta, así que un documento que la carga rechaza lo detiene, y lo que imprime es el rechazo de ese documento como un único diagnóstico: el encabezado con la categoría y el código corto del rechazo, el documento como su origen y, debajo, lo que está mal en el documento — para una infracción del esquema, las claves infringidas con sus líneas y columnas, y el consejo. La carga que lo generó pasó por el directorio que estaba recorriendo y por el paso que leyó el archivo, y estos no se imprimen como marcos propios, porque cada uno volvería a nombrar el mismo documento sin añadir ningún hecho. aggrega serve, cuando se le pregunta a qué se refiere un nombre donde un documento rechazado declara ese nombre, responde con el mismo rechazo en las mismas palabras en una línea, seguido de la nota de que el archivo se omitió en la carga. Como antes, la condición del rechazo sigue siendo identificable por coincidencia en ambos casos.

Ambas formas te llegan dondequiera que se ejecute esa resolución. aggrega build, aggrega pull, aggrega validate --release y aggrega inspect --closure las producen en un terminal, igual que aggrega validate sobre una sola Recipe cuyo destino implements no se encuentra, y un asistente de IA conectado mediante aggrega mcp recibe la misma explicación de las herramientas build y validate, y el rechazo inicial en una sola línea de una lectura catalog:// de una entidad que declara un archivo rechazado. La superficie desde la que preguntaste no cambia nada sobre qué archivo se te indica abrir — a quien llama a aggrega mcp por HTTP se le indica relativo a la raíz del espacio de trabajo, y no se le indica uno fuera del espacio de trabajo que sirve ese servidor — y, cuando un rechazo va primero, el contrato de autoría al que apunta la respuesta es el del tipo que declara ese documento rechazado — no el del tipo de la referencia que falló.

La clase de fallos de la envoltura del documento

Cada documento de entidad — entidades del catálogo, Aggregates, Manifests, Releases — se valida con el esquema JSON publicado de su tipo cuando se carga, antes del análisis tipado. Un documento que infringe su envoltura (una clave desconocida, un campo obligatorio ausente, un valor con la forma equivocada, una construcción prohibida como values: en una Release) detiene la compilación de forma explícita con un diagnóstico que nombra primero la condición, luego el tipo de entidad y el archivo, luego cada clave o forma infractora con la línea y la columna en que se encuentra y, por último, qué hacer al respecto:

[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 schema

El diagnóstico comienza con la condición, nombra el tipo y el archivo, y termina con qué hacer; cada infracción entre ambos lleva solo line:column, ya que el encabezado ya nombró el archivo. Cada clave infractora se informa en su propia posición en lugar de en la posición del bloque que la contiene, de modo que la línea y la columna apuntan a la clave que tienes que cambiar. Cuando la forma de la posición procede de una definición reutilizable del esquema, el diagnóstico nombra esa definición tras la palabra against — against /$defs/boundary arriba — para que quede claro con qué contrato se midió la clave, y la definición no se lea como un paso más a lo largo de la ruta de claves que escribiste. Un documento con varias infracciones las enumera cada una en su propia posición, en orden de clave, y el informe se detiene después de cuatro con un recuento del resto.

Vale la pena saber dos cosas sobre adónde apunta una posición, porque ambas resultan útiles en lugar de sorprendentes:

  • Una clave obligatoria ausente no tiene posición propia — por definición, no está en el documento. La infracción apunta en su lugar a la clave que la contiene, que es donde corresponde la entrada que falta. Así, spec.capability: missing required property apunta a spec:, y es ahí donde la añades.
  • Una clave cuyo propio nombre contiene un punto — cada etiqueta component.aggrega.ai/… y cada anotación features.aggrega.ai/… — se informa en el bloque que la contiene en lugar de en la propia entrada, ya que los puntos se leen como pasos hacia el interior del documento. Una infracción en una etiqueta apunta a labels:.

Cuando una infracción nombra una clave que no está en ninguna parte del documento — por ejemplo, un bloque metadata: entero omitido — la posición se omite en lugar de adivinarse, y la infracción se lee solo como la ruta de la clave y el mensaje. Una posición de la que tendrías que desconfiar es peor que ninguna.

La categoría sigue a la superficie de autoría: [CATALOG_ERROR] para las entidades del catálogo, [DEVELOPER_ERROR] para los Aggregates, [OPS_ERROR] para las Releases y los Manifests. La misma comprobación se ejecuta en cada superficie que carga entidades — aggrega build, aggrega lint, aggrega validate y los diagnósticos del editor que publica aggrega serve — de modo que una clave sobrante o mal escrita se rechaza dondequiera que el documento se lea por primera vez, en lugar de descartarse en silencio. Cada una de esas superficies resuelve la posición de la misma manera, así que apuntan a la misma clave, y cada una lee la frase de la condición de la propia condición: la línea que subraya tu editor es la línea que nombra el terminal, y la frase con la que empieza la entrada del editor es la frase con la que empieza el terminal. Lo que las dos superficies no comparten es el mensaje completo, y es deliberado — el terminal agrupa cada hallazgo bajo un único encabezado y termina con el consejo para la ruta, mientras que el editor emite una entrada por hallazgo, situada en su propia clave, sin repetir ni el archivo al que ya está asociada ni un consejo que, de otro modo, repetiría en cada subrayado. Así que la parte que converge es aquella por la que reconoces la condición.

Cadenas de errores múltiples

Cuando una única compilación detecta varias infracciones independientes (lo más habitual durante el análisis estático, donde cada infracción de selector y de appliesTo se recoge antes de que cualquiera de ellas detenga la compilación), los errores se unen en una sola cadena. La CLI recorre la cadena y presenta cada suberror de forma independiente, separados por una línea horizontal:

[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.

El separador --- es literal — los lectores y las herramientas posteriores pueden dividir por él para enumerar los errores unidos. Cada suberror es un fallo por derecho propio y no un detalle de su vecino, así que cada uno lleva un encabezado propio: su propia categoría y su propio código corto, cada uno donde lo tenga, como describe la sección sobre tokens ausentes. Dos infracciones de una misma regla nombran el mismo código corto, como arriba; dos infracciones de reglas distintas nombran códigos distintos.

Leer un error de principio a fin

En la mayoría de los contextos de autoría, el prefijo de categoría y el puntero a la fuente identifican juntos qué corregir:

CategoríaDónde está la correcciónSuperficies de ejemplo
[DEVELOPER_ERROR]YAML del AggregateInfracciones de selector / appliesTo en lo que escribió el Aggregate; discrepancia del socket uses del lado del Aggregate; detenciones del resolvedor en la autoría del desarrollador.
[OPS_ERROR]YAML de la Release / YAML del ManifestLa plantilla de ruta del límite hace referencia a un campo no admitido; subDirectory provoca una colisión de rutas; detenciones del resolvedor en la autoría de la Release; una conexión que la Release cablea, o una vinculación que rellena en una conexión, rechazados por las reglas del socket o del slot; una Feature que solo la Release adjunta, a un componente o a un límite, rechazada por las reglas de la Feature o del slot; se rechaza un mapping o un enlace de anotación de un Manifest.
[CATALOG_ERROR]Recipe / FeatureRecipe / Component / Feature / PluginReglas de forma de la Recipe; la plantilla de la FeatureRecipe hace referencia a un campo exclusivo de cada componente con executionScope: boundary; falla la comprobación cruzada de featuresSchema del Workload.
[TRANSLATION_ERROR]Workload / salida de valuesMapping / overlay de origenResolución del puerto de sondeo de Helm; colisión de nombres de servicio de compose entre límites; dos contribuyentes de compose que declaran un mismo nombre de volumen o de config de nivel superior con cuerpos en conflicto; discrepancia del nombre del chart en el umbrella helm-chart.
[FETCH_ERROR]Obtención desde el registro / origen remoto (operativa, no de autoría)Artefacto no encontrado en el registro; autenticación requerida; red inalcanzable; discrepancia del digest en caché con el archivo de bloqueo. Corrección: autentícate, restablece la conectividad o aggrega pull --upgrade --release <release>.
[POLICY_ERROR]Plugin de políticas (regla de gobernanza)Un plugin de políticas adjunto en un rol de veredicto de gobernanza rechazó la compilación ensamblada según una regla que aplica. Corrección: cumple la política aplicada o reconsidera la vinculación.
[TRUST_ERROR]Configuración de confianza, o la propia firma del artefacto (un ámbito, no una superficie de autoría)Una política de confianza o una raíz de confianza fijada ilegible; una política sin clave que no declara ninguna identidad de confianza; una política de firma que exige una firma para el tipo que se publica; una puerta de vinculación de veredicto registrada que la configuración ya no vincula. O bien: una firma que no se verifica; un artefacto que no lleva ninguna donde se requiere una; un firmante no confiable; un plugin cuya identidad de confianza registrada ya no coincide. Corrección: corrige la configuración o el registro de confianza versionado, o decide sobre el artefacto — el código corto indica cuál.

Los prefijos de contexto por proveedor (helm: node "<id>": ..., compose: node "<id>": ...) aparecen dentro de la parte del mensaje de las salidas [TRANSLATION_ERROR] y [CATALOG_ERROR] para localizar el proveedor que falla cuando hay más de un proveedor en juego.

Errores nativos de bibliotecas

Los errores que se originan dentro de una biblioteca subyacente (errores de carga de charts del SDK de Helm, errores del analizador YAML de docker-compose, errores de E/S de archivos por una ruta de origen ausente) se envuelven con el prefijo de contexto por proveedor y aparecen bajo [TRANSLATION_ERROR] o [CATALOG_ERROR] según se hayan producido en la síntesis o en la carga del contenido del catálogo. El mensaje envuelto de la biblioteca conserva literalmente el diagnóstico de la herramienta original para que los autores puedan cotejarlo con la propia documentación de la herramienta.

Referencias cruzadas

  • fatal-halts.md — catálogo, error por error, de cada detención fatal con su mensaje previsto y cómo corregirla.
  • warnings.md — avisos no fatales que emite el compilador.
  • vocabulary/validation-surface.md — las cuatro capas de validación de esquemas y cómo interactúan sus formas de error.