Disciplina de tradução de erros
O pipeline de compilação da Aggrega emite erros a partir de muitas superfícies — validadores de esquema, o resolvedor, o construtor do IR, os provedores, o mecanismo de templates Go e as bibliotecas YAML / Helm / docker-compose subjacentes que os provedores encapsulam. Os erros que chegam até a CLI começam com um cabeçalho entre colchetes que indica até duas coisas — uma categoria, que diz qual área examinar (para a maioria dos valores, a superfície de autoria com a falha), e o código curto da condição que interrompeu o build — seguido de um ponteiro de origem e de uma mensagem. Quando um plugin gerou a condição, o código é qualificado pelo plugin que a gerou, porque mais de um plugin pode relatar a mesma condição. Esta página documenta a forma dessa saída para que os autores interpretem as mensagens de erro diretamente.
Para o catálogo de cada erro (todas as interrupções fatais com orientações de correção), veja fatal-halts.md. Para as quatro camadas de validação de esquema e como as formas dos seus erros interagem, veja vocabulary/validation-surface.md.
As categorias de erro
Uma tag de categoria diz qual área examinar. A maioria nomeia a superfície de autoria onde está a correção; as demais nomeiam uma área que não é erro de autoria de ninguém — a obtenção de um artefato, um veredito de governança, ou confiança e assinatura — e o código curto ao lado da categoria no cabeçalho é o que identifica a condição específica em todos os casos:
[DEVELOPER_ERROR]— a falha diz respeito à autoria do Aggregate. A correção está no YAML do Aggregate ou na parte do catálogo escrita pelo desenvolvedor (valores de Component, socketsuses, vinculações de Feature). Superfícies de exemplo: interrupções do resolvedor por problemas do lado do Aggregate; violações de seletor e deappliesTonaquilo que o Aggregate escreveu.[OPS_ERROR]— a falha diz respeito aos documentos do próprio operador, a Release e o Manifest. A correção está no YAML da Release (topologia de fronteiras, valores de parâmetros, vinculações de Feature no nível da Release) ou no YAML do Manifest (por meio de qual Recipe um tipo é implantado, e os bindings de anotação escritos ao lado). Superfícies de exemplo: validação do esquema da Release; avaliação de templates de caminhos de fronteira; colisões desubDirectoryentre provedores; recusas de mapeamentos e de bindings de anotação do Manifest; uma regra que recusa uma conexão que a Release liga, ou uma vinculação que ela preenche em uma conexão — o seletor de um socket, o seletor de um slot, um slot que um socket declara obrigatório; uma regra que recusa uma Feature que só a Release vincula, a um componente ou a uma fronteira — oappliesToda Feature, o seletor de um slot, seu esquema declarado.[CATALOG_ERROR]— a falha diz respeito a uma entidade do catálogo (Recipe, FeatureRecipe, Component, Feature, Plugin). A correção está no conteúdo do catálogo. Superfícies de exemplo: regras de forma da Recipe; verificações cruzadas defeaturesSchemado Workload; erros de parsing de templates em templates escritos no catálogo.[TRANSLATION_ERROR]— a falha diz respeito à síntese do lado do provedor (um plugin de provedor tentando traduzir um Workload, a saída de um valuesMapping ou uma sobreposição com origem em artefatos nativos do provedor). A correção normalmente está na formaservices/containers/volumesdo Workload, na saída do templatevaluesMappingda Recipe ou na estrutura da sobreposição em modo de origem.[FETCH_ERROR]— a falha diz respeito à obtenção de uma dependência fixada a partir de um registry ou de uma origem remota, não a uma superfície de autoria. A correção costuma ser operacional: autenticar-se no registry (docker login <registry>), restaurar a conectividade ou fixar novamente um artefato divergente ou adulterado (aggrega pull --upgrade --release <release>). Superfícies de exemplo: uma entidade de catálogo ou um chart não encontrado no registry; autenticação exigida ou com falha; a rede inacessível; o digest de um artefato em cache que não corresponde ao lockfile. Os erros de obtenção trazem na mensagem uma indicação concreta de correção.[POLICY_ERROR]— o build foi rejeitado por um plugin de política vinculado em um papel de veredito de governança. Não é uma falha de superfície de autoria: a entrada está bem formada, mas falha em uma regra de governança (conformidade, FinOps ou segurança) que o plugin impõe. A correção é colocar o que você escreveu em conformidade com a política imposta, ou reconsiderar a vinculação da política. A mensagem indica o plugin que rejeitou e traz a mensagem de regra que ele forneceu.[TRUST_ERROR]— a camada de confiança e assinatura recusou a operação. Esta categoria nomeia uma área em vez de uma superfície de autoria, e cobre duas soluções que você distingue pelo código curto ao lado. Sua configuração de confiança está errada: uma política de confiança que não pode ser lida, uma raiz de confiança fixada que não pode ser carregada, uma política keyless que não declara nenhuma identidade confiável, uma política de assinatura que exige assinatura para o tipo de artefato que você está publicando, ou um plugin registrado como confiável para uma vinculação de veredito que sua configuração não vincula mais. Este artefato falhou na verificação: uma assinatura que não é verificada em relação à âncora de confiança, um artefato sem assinatura onde uma é exigida, uma assinatura de um signatário real mas não confiável, ou um plugin cuja identidade confiável registrada não corresponde mais ao que é resolvido. No primeiro caso, a correção está na sua configuração ou no registro de confiança commitado; no segundo, é uma decisão sobre o artefato — restaurar o que foi revisado, ou revisar e registrar novamente o que mudou.
Um achado sobre uma vinculação de Feature segue o documento que a escreveu
Uma Feature pode ser vinculada em qualquer um dos documentos — o Aggregate vincula uma em um componente ou em um subsistema, a Release em sua entrada para um componente ou em uma fronteira — então a categoria de um achado sobre uma vinculação é lida a partir de onde a vinculação foi escrita, não do componente que ela alcança. O achado é posicionado na entrada features: que escreveu a vinculação, naquele documento, e é atribuído ao autor daquele documento: uma vinculação que só a Release faz é relatada no caminho da própria Release como [OPS_ERROR], e uma que o Aggregate faz, no caminho do 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.Quando os dois documentos escrevem uma mesma vinculação — o Aggregate nomeando sua Feature, a Release dimensionando-a — um achado sobre a vinculação como um todo é posicionado onde sua Feature é nomeada, ou seja, no Aggregate. Um achado sobre uma parte da sua configuração é posicionado onde essa parte foi escrita: seus values são do desenvolvedor, no Aggregate, e seu infra do operador, na Release. Uma vinculação produzida pela expansão orientada por anotações não foi escrita por nenhuma entrada features:, então um achado sobre ela é posicionado no componente, no documento que declara o componente, como [DEVELOPER_ERROR].
Um slot obrigatório deixado vazio é o único caso que nenhum documento escreveu. Não há vinculação para onde apontar, então o achado fica no componente no Aggregate e é classificado como [DEVELOPER_ERROR], e sua solução nomeia os dois documentos, porque qualquer um deles pode preencher o slot: “Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it.” (Vincule uma Feature com esse nome, no Aggregate ou na Release, no componente ou em um escopo acima dele.)
O editor lê o mesmo posicionamento: um achado posicionado na Release é mostrado no documento da Release, na chave que o escreveu, e não aparece de forma alguma no do Aggregate; um achado posicionado no documento de um módulo que o Aggregate importa é mostrado da mesma forma no documento desse módulo.
Formato da saída
Um diagnóstico impresso começa com o cabeçalho entre colchetes e o ponteiro de origem, e coloca a mensagem em uma linha própria com recuo:
[CATEGORY SHORTCODE] <source> <message>O cabeçalho traz dois tokens, e eles respondem a perguntas diferentes. A categoria é uma das descritas acima e diz qual área examinar. O código curto é a letra E seguida de quatro dígitos, e nomeia a condição exata que interrompeu a compilação: cite-o em um relatório, digite-o em uma busca ou resolva-o na tabela de todas as condições em sentinels.md. Nenhum dos dois pode ser deduzido do outro, e é por isso que ambos são impressos — e, onde uma categoria cobre mais de uma solução, como acontece com [TRUST_ERROR], é o código curto que diz qual delas você encontrou.
Um código gerado por um plugin é qualificado pelo plugin que o gerou
Cada código curto nomeia uma condição que Aggrega declara, e duas condições nunca compartilham um: uma condição declarada sob um número que outra condição já detém é recusada antes que o compilador leia qualquer entrada. Um plugin não aloca códigos próprios. Quando relata uma falha, ele nomeia uma das condições que Aggrega declara — uma das poucas condições gerais que descrevem como um plugin falhou, ou uma mais específica quando houver uma adequada — e fornece a frase que diz o que de fato aconteceu. Assim, dois plugins podem relatar o mesmo código curto e, quando o fazem, estão relatando a mesma condição.
O que o código não consegue dizer é qual plugin encontrou a condição, e um cabeçalho que relata uma condição gerada por um plugin traz a identidade do plugin imediatamente antes do código:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>O código curto é sempre o segmento final — a letra E seguida de quatro dígitos, depois da última /. A identidade de um plugin traz separadores próprios, e pode trazer uma versão, então ler a partir do fim, e não a partir da primeira /, é o que torna o código recuperável de qualquer cabeçalho. Tudo o que vem antes desse segmento final é o plugin.
O segmento final é resolvido como qualquer outro código curto, seja qual for o plugin que o gerou: a tabela de todas as condições em sentinels.md o lista, e aggrega explain o resolve. Cite apenas o segmento final — o qualificador diz qual plugin encontrou a condição, não qual condição é. Um plugin que nomeia um código que Aggrega não declara — um número que nenhuma condição detém, ou um código aposentado — não tem esse código impresso: a compilação é interrompida em E0293, qualificado por esse plugin, e sua mensagem cita o código que o plugin ofereceu, nomeia essas condições gerais e mantém a frase do próprio plugin.
Um cabeçalho que imprime um código curto sem qualificador relata uma condição gerada pelo próprio Aggrega, o que inclui o caso em que um plugin falhou e não nomeou nenhuma condição própria. Nesse caso, o que interrompeu a compilação foi a condição genérica de falha de plugin do compilador, e a mensagem do plugin traz o detalhe.
Qualquer um dos tokens pode estar ausente, e um token ausente é omitido
Nada jamais ocupa o lugar de um token que o diagnóstico não tem — nenhum espaço reservado, nenhum colchete vazio. Há três maneiras de um cabeçalho ficar reduzido, e cada uma diz algo a você:
- Sem código curto. A falha não nomeia nenhuma condição própria de Aggrega — na maioria das vezes, trata-se de um erro relatado por uma biblioteca que o compilador encapsula. O cabeçalho imprime apenas a categoria, então você ainda sabe qual superfície examinar.
- Sem categoria. A falha não tem nenhuma área para a qual encaminhar você, então nenhuma é adivinhada. O cabeçalho imprime apenas o código curto, e é o código que você resolve. Duas situações produzem isso, e elas se leem da mesma forma porque, para os seus propósitos, são iguais — nenhuma diz onde olhar, e o código diz o que aconteceu. Uma é um defeito no próprio compilador, em que a mensagem diz isso e pede que você o relate; o caso que ocorre é o das próprias visões do compilador sobre o catálogo discordarem entre si. A outra é uma falha que nomeia uma condição, mas nunca passou por uma superfície que a classifique sob uma área, que é a forma usual de uma recusa gerada no limite do comando. Uma categoria nunca é inventada para preencher a lacuna, e esse é o propósito da omissão, não uma limitação dela: a categoria responde a “qual área eu examino”, e uma resposta dada onde a pergunta não tem nenhuma não é uma resposta cautelosa, mas uma errada, sobre a qual se age primeiro. Vale dizer também que a inferência inversa não se sustenta: um cabeçalho que traz uma categoria nem sempre aponta para algo que você escreveu, porque
[FETCH_ERROR],[POLICY_ERROR]e[TRUST_ERROR]nomeiam, cada um, uma área em vez de uma superfície de autoria. - Nenhum dos dois. Os colchetes são omitidos por completo e o diagnóstico é a sua mensagem. Trata-se de uma falha que não nomeia nenhuma condição própria de Aggrega e não tem nenhuma área para a qual encaminhar você: um comando que recusa seus argumentos, um arquivo que ele não consegue ler, um cancelamento ou um erro relatado por uma biblioteca que o compilador encapsula sem nenhuma condição nossa por baixo. Não há nada a resolver em
sentinels.md, e a mensagem é tudo o que a falha tem a dizer.
O mesmo erro reduzido a uma linha, a forma adequada para saída de log e não para um terminal, traz a categoria e descarta o código curto:
[CATEGORY] <source>: <message>Uma categoria ausente do cabeçalho também está ausente aqui, colchetes incluídos, então esta linha nunca é [] <source>: <message>. A forma de uma linha é reencapsulada nos quadros que a envolvem à medida que a falha sobe, então uma tag vazia seria levada para cada um deles.
A origem é um ponteiro estruturado — tipicamente <file>:<line>:<column> quando há uma posição YAML disponível, ou um identificador lógico (o nome da entidade do catálogo, o nome da Release, o caminho da fronteira) quando nenhuma posição de arquivo se aplica. Uma terceira forma, <file> at <key>, aparece quando o ponteiro conhece tanto o documento quanto a chave de autoria dentro dele, mas nenhuma posição em bytes: o arquivo é o que você abre, e a chave é o que olhar depois de aberto. A mensagem é o diagnóstico específico da superfície.
Uma falha sobre uma instância do seu build — um componente, um componente que um módulo fornece ou o próprio módulo — nomeia essa instância depois da posição, como (instance <name>), de modo que aggregate.yaml (instance shop) é o Aggregate que declara o módulo shop. Quando a falha não tem nenhum documento para o qual apontar, a instância aparece sozinha como instance <name>: um provedor que falha ao renderizar o componente adminer imprime [TRANSLATION_ERROR E0082] instance adminer, e as linhas abaixo dele trazem o restante da falha, incluindo qualquer documento que ela nomeie. O nome é aquele sob o qual o Aggregate declara o componente; um componente que um módulo fornece é nomeado pelo seu caminho através do módulo, como shop.cart. Uma instância nunca é impressa onde cabe um arquivo, então aquilo com que a origem começa é sempre um documento que você pode abrir, ou um dos identificadores lógicos acima.
Uma regra avaliada sobre o grafo concluído relata nessa terceira forma, e a chave é o que distingue dois achados quando a mensagem sozinha não consegue. Uma regra desse tipo nomeia o tipo de componente declarante em vez da instância, então dois componentes de um mesmo tipo que violam a mesma regra trazem a mesma mensagem sobre o mesmo arquivo:
[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")A chave é a única parte que difere, e é ela que indica qual dos dois componentes editar. Ambos os achados trazem o mesmo código curto porque ambos são a mesma condição, encontrada duas vezes — o código curto nomeia a regra, e a chave nomeia a ocorrência.
Mais duas linhas fazem parte da forma, para uma falha que traz o contexto para preenchê-las — a expressão de template que falhou e um instantâneo dos pilares disponíveis no ponto em que falhou:
[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>A linha expression: traz o trecho de template que disparou a falha. O bloco active pillars: lista as chaves de pilar de nível superior disponíveis no ponto da falha, para que os autores vejam o que podia ser consultado. Ambos são omitidos quando a falha não traz nenhum dos dois.
Quadros de contexto aninhados
Um erro frequentemente passa por mais de uma superfície a caminho da CLI: uma fase de carregamento encapsula a falha específica da entidade, que por sua vez encapsula um sentinela que explica a regra. Cada quadro categorizado dessa cadeia é renderizado — o mais externo como o cabeçalho na forma acima, cada quadro aninhado como uma continuação caused by: com recuo que traz sua própria tag de categoria, seu próprio ponteiro de origem e sua própria mensagem. O quadro mais interno que aponta para um arquivo está sempre visível:
[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")Apenas o cabeçalho traz um código curto, e as continuações trazem apenas sua categoria. A condição é nomeada uma vez, no ponto em que o leitor encontra a falha; os quadros abaixo de um marcador caused by: são essa mesma falha vista mais de dentro, então repetir seu identificador em cada um acrescentaria linhas sem acrescentar fatos. Um bloco note: não é uma continuação e não segue esta regra — ele relata condições de outros documentos, e não a mesma vista mais de dentro; a seção abaixo trata dele. O código que o cabeçalho imprime é o que a cadeia nomeia — aqui a regra lá no fundo —, então um quadro de contexto de fase no topo ainda identifica a condição que está por baixo.
Lendo de cima para baixo: a fase que falhou, depois a entidade (com seu caminho de arquivo) que causou a falha, depois a regra que ela violou. Um quadro aninhado que não acrescenta nada além do seu pai (mesma categoria, mesma origem, uma mensagem que o pai já contém) é deduplicado em vez de repetido, e uma explicação terminal só é renderizada quando os quadros acima dela ainda não trazem seu texto.
Uma cadeia fica mais profunda sempre que uma falha passa por mais superfícies em seu caminho para fora, e a regra vale em qualquer profundidade. Um template recusado dentro do Workload sintetizado de uma Recipe passa por três — o nó sendo renderizado, a superfície de templates da Recipe e o próprio template:
[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)Leia-a de cima para baixo como antes, e observe três coisas que a profundidade extra torna visíveis. O código curto aparece uma vez, no cabeçalho, por mais continuações que o sigam. O quadro mais interno é onde fica a frase própria da condição, então a linha mais profunda é tanto aquela com que fazer a correspondência quanto aquela que diz o que mudar. E um quadro sem ponteiro de origem imprime apenas sua categoria: o quadro do meio acima nomeia em sua mensagem a superfície em que falhou, porque essa superfície é um template e não um arquivo, e não tem uma posição para a qual apontar.
Quando a falha se ramifica sob um quadro — uma fase que coletou várias violações independentes antes de parar —, a continuação traz uma contagem, e cada falha coletada é renderizada abaixo dela, separada pela mesma linha --- que as cadeias de múltiplos erros abaixo usam:
[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 itAs falhas coletadas sob a contagem também são continuações, então nenhuma delas repete o código curto do cabeçalho — e é isso que impede que uma ramificação de uma dúzia de violações imprima o mesmo identificador uma dúzia de vezes.
Uma única gramática de separadores se aplica em todo lugar: --- entre falhas irmãs, caused by: entre quadros de contexto aninhados.
Um arquivo de catálogo recusado e a falha que ele explica
Carregar um catálogo para resolver aquilo de que uma Release depende é tolerante de propósito: um arquivo que não pode ser lido, ou um documento Aggrega que não pode ser analisado ou indexado, é recusado e registrado em vez de abortar todo o carregamento. É isso que impede que uma entidade com defeito que sua Release nunca toca faça falhar uma compilação não relacionada.
A consequência é que um arquivo recusado some do catálogo silenciosamente — e, se a sua Release de fato o alcança, o que falha é a tentativa de resolver uma referência ao que esse arquivo declarava. Essa falha é uma consequência da recusa, e não a recusa em si, então o relatório coloca as duas em ordem causal sempre que consegue nomear a recusa com exatidão:
[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"A recusa vem primeiro, com sua própria categoria e seu próprio código curto, porque nomeia aquilo sobre o que você pode agir: a correção é um implements: ausente em uma Recipe, e não algo sobre como uma referência é procurada em um registro. A falha de resolução continua sendo relatada, abaixo dela, porque é ela que diz por que aquele documento era necessário.
Uma recusa vem primeiro somente quando exatamente um arquivo recusado declara a identidade que a referência com falha nomeia. A correspondência é feita pela identidade que cada documento declara para si — seu tipo, seu nome, sua versão e, para uma receita, a spec.capability que a delimita —, então um arquivo recusado que declara o que a referência pede é o arquivo para o qual essa referência teria sido resolvida. Duas consequências decorrem disso. Uma referência que indica um intervalo de versões em vez de uma versão não nomeia nenhum documento único, então não destaca nada. E um documento malformado demais para que seu cabeçalho possa ser lido não declara identidade alguma, então nunca é apontado como causa de nada.
Quando nenhum arquivo recusado declara essa identidade, ou mais de um declara, o relatório é o que seria sem registro de recusas: a falha vem primeiro, e cada recusa é listada abaixo dela para que você a avalie. Apontar o arquivo errado como causa seria pior do que não apontar nenhum, porque você agiria com base nisso.
[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 schemaVale a pena saber algumas coisas sobre essa segunda forma, porque cada uma responde a uma pergunta que o bloco levantaria de outro modo.
O cabeçalho nomeia a falha, não uma recusa. O código curto no topo é o que a falha de resolução gerou, porque é essa falha que vem primeiro aqui — nenhum arquivo recusado foi destacado, então nenhum deles encabeça a linha. Ele não traz nenhuma categoria ao lado porque nada neste caminho classificou a falha sob uma área. O cabeçalho próprio de cada recusa fica em sua própria entrada abaixo, que é onde você o lê.
Toda recusa é listada, não apenas a que importava. Chegar a esta forma significa que o registro não conseguiu destacar uma só, então a nota expõe a distinção em vez de adivinhar: uma recusa fora do fechamento desta Release é tolerada e não pode ser o que falhou, o que deixa uma recusa que nomeia algo que a Release alcança como a única entrada que explica a falha. Leia as entradas à luz do que a sua Release realmente usa.
Cada entrada traz seu próprio cabeçalho entre colchetes — sua própria categoria e seu próprio código curto. Este é o único lugar em que um código curto aparece abaixo do cabeçalho do diagnóstico, e isso não é uma exceção à regra das continuações acima, mas uma consequência dela: uma entrada sob note: não é a mesma falha vista mais de dentro, é uma condição diferente gerada por um documento diferente. Nomear sua condição é o que permite que você procure a recusa e corrija o arquivo, que é a ação que o bloco existe para possibilitar.
Um arquivo recusado cujo cabeçalho estava malformado demais para recuperar a identidade que declara é listado apenas pelo caminho. Essa é a leitura honesta de um documento que nada conseguiu espiar, e o caminho ainda basta para abrir o arquivo. Um arquivo malformado demais até para que seu tipo seja lido — um que não é analisado como YAML, por exemplo — é listado dessa forma quando declara uma apiVersion de Aggrega, por meio de uma linha que começa, sem recuo, com apiVersion: e um valor que começa com aggrega.ai/, com o motivo dado pelo próprio parser: a linha, e o que o parser esperava ali. Um arquivo YAML que declara outra apiVersion, ou nenhuma, não é um documento Aggrega — o template de um chart, por exemplo, ou um arquivo de configuração mantido ao lado das entidades —, então nunca é listado, por mais malformado que esteja.
Um arquivo que declara um tipo que nenhum catálogo contém só é nomeado onde explica a falha. Um documento que declara uma apiVersion de Aggrega e um kind que nenhum catálogo contém — um Componnent com erro de digitação, por exemplo — é ignorado por todo carregamento, então não é uma recusa e não é listado entre elas. Quando a referência com falha pede o nome que esse arquivo declara, e a versão quando a referência indica uma, o relatório o nomeia em uma nota própria abaixo da falha, seja qual for o tipo como o qual a referência foi coletada — em cada superfície listada abaixo, e em aggrega build, quer ele leia um lockfile existente, quer preencha um primeiro:
[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 directoriesA falha continua vindo primeiro: o tipo que o arquivo declara não nomeia nenhuma identidade, então o arquivo nunca é destacado como a recusa com que o relatório começa. A explicação de onde as entidades locais são lidas fica de fora desse relatório, porque o arquivo já está onde o catálogo lê e movê-lo não ajudaria. Um arquivo de um tipo que nenhum catálogo contém e que declara algum outro nome não explica nada sobre esta falha e não é mencionado. aggrega serve, cujas mensagens ocupam uma linha, traz a mesma nota nessa linha — 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 da recusa do arquivo — e nunca lista esse arquivo entre os arquivos ignorados no carregamento; a ferramenta describe de aggrega mcp, quando consultada sobre um nome nos termos de uma Release, também o nomeia no lugar dessa explicação. aggrega validate e aggrega lint sobre o catálogo inteiro relatam cada um desses arquivos, quer algo o alcance, quer não — veja fatal-halts.md §“A catalog document declares a kind a catalog does not hold (Um documento de catálogo declara um tipo que um catálogo não contém)”.
Seja qual for a forma que você receber, a falha mantém sua própria identidade. A nota é acrescentada à falha em vez de renderizada por cima dela, e colocar uma recusa primeiro muda apenas o que você lê primeiro — então a condição que a falha gerou permanece intacta em qualquer caso: seu código curto continua sendo resolvido, e uma ferramenta que faz a correspondência pela condição continua a encontrá-la.
Quando o documento recusado é ele mesmo o que um comando relata, a recusa é enunciada uma única vez. aggrega inspect <name> carrega o catálogo de forma estrita, então um documento que o carregamento recusa o interrompe, e o que ele imprime é a recusa desse documento como um único diagnóstico: o cabeçalho com a categoria e o código curto da recusa, o documento como sua origem e, abaixo, o que está errado no documento — para uma violação de esquema, as chaves violadas com suas linhas e colunas, e a orientação. O carregamento que a gerou passou pelo diretório que estava percorrendo e pela etapa que leu o arquivo, e estes não são impressos como quadros próprios, porque cada um nomearia o mesmo documento de novo sem acrescentar um fato. aggrega serve, quando perguntado a que um nome se refere onde um documento recusado declara esse nome, responde com a mesma recusa nas mesmas palavras em uma linha, seguida da nota de que o arquivo foi ignorado no carregamento. Como acima, a condição da recusa continua identificável por correspondência em qualquer caso.
As duas formas chegam até você onde quer que essa resolução seja executada. aggrega build, aggrega pull, aggrega validate --release e aggrega inspect --closure as produzem em um terminal, assim como aggrega validate sobre uma Recipe cujo destino implements não é encontrado, e um assistente de IA conectado por meio de aggrega mcp recebe a mesma explicação das ferramentas build e validate, e a recusa que vem primeiro, em uma única linha, de uma leitura catalog:// de uma entidade que um arquivo recusado declara. A superfície a partir da qual você perguntou não muda nada sobre qual arquivo você é orientado a abrir — a quem chama aggrega mcp por HTTP, ele é indicado em relação à raiz do espaço de trabalho, e não lhe é indicado um arquivo fora do espaço de trabalho que esse servidor atende — e, onde uma recusa vem primeiro, o contrato de autoria para o qual a resposta aponta é o do tipo que esse documento recusado declara — não o do tipo da referência que falhou.
A classe de falhas do envelope do documento
Todo documento de entidade — entidades do catálogo, Aggregates, Manifests, Releases — é validado contra o esquema JSON publicado do seu tipo quando é carregado, antes da análise tipada. Um documento que viola o seu envelope (uma chave desconhecida, um campo obrigatório ausente, um valor com a forma errada, uma construção proibida como values: em uma Release) interrompe o build de forma explícita com um diagnóstico que nomeia primeiro a condição, depois o tipo de entidade e o arquivo, depois cada chave ou forma infratora com a linha e a coluna em que está e, por fim, o que fazer a respeito:
[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 schemaO diagnóstico começa com a condição, nomeia o tipo e o arquivo e termina com o que fazer; cada violação entre eles traz apenas line:column, pois o cabeçalho já nomeou o arquivo. Cada chave infratora é informada na sua própria posição, e não na posição do bloco que a contém, de modo que a linha e a coluna apontam para a chave que você precisa alterar. Quando a forma da posição vem de uma definição reutilizável no esquema, o diagnóstico nomeia essa definição após a palavra against — against /$defs/boundary acima — para que fique claro contra qual contrato a chave foi medida e para que a definição não seja lida como mais um passo ao longo do caminho de chaves que você escreveu. Um documento com várias violações lista cada uma na sua própria posição, em ordem de chave, e o relatório para depois de quatro com uma contagem das restantes.
Vale a pena saber duas coisas sobre para onde uma posição aponta, porque ambas são úteis em vez de surpreendentes:
- Uma chave obrigatória ausente não tem posição própria — por definição, ela não está no documento. A violação aponta, em vez disso, para a chave que a envolve, que é onde a entrada ausente deve ficar. Assim,
spec.capability: missing required propertyaponta paraspec:, e é ali que você a adiciona. - Uma chave cujo próprio nome contém um ponto — todo rótulo
component.aggrega.ai/…e toda anotaçãofeatures.aggrega.ai/…— é informada no bloco que a contém, e não na própria entrada, pois os pontos são lidos como passos para dentro do documento. Uma violação em um rótulo aponta paralabels:.
Quando uma violação nomeia uma chave que não está em lugar nenhum do documento — um bloco metadata: inteiro omitido, por exemplo — a posição é omitida em vez de adivinhada, e a violação é lida apenas como o caminho da chave e a mensagem. Uma posição da qual você precisaria desconfiar é pior do que nenhuma.
A categoria segue a superfície de autoria: [CATALOG_ERROR] para entidades do catálogo, [DEVELOPER_ERROR] para Aggregates, [OPS_ERROR] para Releases e Manifests. A mesma verificação é executada em toda superfície que carrega entidades — aggrega build, aggrega lint, aggrega validate e os diagnósticos do editor que aggrega serve publica — de modo que uma chave sobrando ou com erro de digitação é rejeitada onde quer que o documento seja lido pela primeira vez, em vez de ser descartada silenciosamente. Cada uma dessas superfícies resolve a posição da mesma forma, então elas apontam para a mesma chave, e cada uma lê a frase da condição a partir da própria condição: a linha que o seu editor sublinha é a linha que o terminal nomeia, e a frase com que a entrada do editor começa é a frase com que o terminal começa. O que as duas superfícies não compartilham é a mensagem inteira, e isso é deliberado — o terminal agrupa cada achado sob um único cabeçalho e termina com a orientação para o caminho, enquanto o editor emite uma entrada por achado, posicionada na sua própria chave, sem repetir nem o arquivo ao qual já está associada nem uma orientação que, de outra forma, repetiria a cada sublinhado. Assim, a parte que converge é aquela pela qual você reconhece a condição.
Cadeias de múltiplos erros
Quando uma única compilação detecta várias violações independentes (mais comumente durante a análise estática, em que toda violação de seletor e de appliesTo é coletada antes que qualquer uma interrompa o build), os erros são unidos em uma única cadeia. A CLI percorre a cadeia e apresenta cada suberro de forma independente, separados por uma linha 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.O separador --- é literal — leitores e ferramentas posteriores podem dividir por ele para enumerar os erros unidos. Cada suberro é uma falha por si só, e não um detalhe do seu vizinho, então cada um traz um cabeçalho próprio: a sua própria categoria e o seu próprio código curto, cada um quando existe, como descreve a seção sobre tokens ausentes. Duas violações de uma mesma regra nomeiam o mesmo código curto, como acima; duas violações de regras diferentes nomeiam códigos diferentes.
Lendo um erro de ponta a ponta
Na maioria dos contextos de autoria, o prefixo de categoria e o ponteiro para a origem identificam juntos o que corrigir:
| Categoria | Onde fica a correção | Superfícies de exemplo |
|---|---|---|
[DEVELOPER_ERROR] | YAML do Aggregate | Violações de seletor / appliesTo no que o Aggregate escreveu; incompatibilidade do socket uses do lado do Aggregate; interrupções do resolvedor na autoria do desenvolvedor. |
[OPS_ERROR] | YAML da Release / YAML do Manifest | O template de caminho da fronteira referencia um campo não suportado; subDirectory causa colisão de caminhos; interrupções do resolvedor na autoria da Release; uma conexão que a Release estabelece, ou uma vinculação que ela preenche em uma conexão, recusados pelas regras do socket ou do slot; uma Feature que apenas a Release anexa, a um componente ou a uma fronteira, recusada pelas regras da Feature ou do slot; um mapeamento ou uma associação de anotação de um Manifest é recusado. |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Regras de forma da Recipe; o template da FeatureRecipe referencia um campo exclusivo de cada componente com executionScope: boundary; a verificação cruzada de featuresSchema do Workload falha. |
[TRANSLATION_ERROR] | Workload / saída de valuesMapping / overlay de origem | Resolução da porta de probe do Helm; colisão de nomes de serviço do compose entre fronteiras; dois contribuidores do compose declarando um mesmo nome de volume ou de config de nível superior com corpos conflitantes; incompatibilidade de nome de chart no umbrella helm-chart. |
[FETCH_ERROR] | Aquisição a partir do registry / origem remota (operacional, não de autoria) | Artefato não encontrado no registry; autenticação necessária; rede inacessível; digest em cache incompatível com o arquivo de bloqueio. Correção: autentique-se, restaure a conectividade ou aggrega pull --upgrade --release <release>. |
[POLICY_ERROR] | Plugin de política (regra de governança) | Um plugin de política anexado em um papel de veredito de governança rejeitou o build montado com base em uma regra que ele aplica. Correção: atenda à política aplicada ou reconsidere a vinculação. |
[TRUST_ERROR] | Configuração de confiança, ou a própria assinatura do artefato (uma área, não uma superfície de autoria) | Uma política de confiança ou uma raiz de confiança fixada ilegível; uma política keyless que não declara nenhuma identidade confiável; uma política de assinatura que exige uma assinatura para o tipo sendo publicado; um gate de vinculação de veredito registrado que a configuração não vincula mais. Ou: uma assinatura que não é verificada; um artefato sem nenhuma onde uma é exigida; um signatário não confiável; um plugin cuja identidade confiável registrada não corresponde mais. Correção: corrija a configuração ou o registro de confiança versionado, ou decida sobre o artefato — o código curto diz qual. |
Os prefixos de contexto por provedor (helm: node "<id>": ..., compose: node "<id>": ...) aparecem dentro da parte da mensagem das saídas [TRANSLATION_ERROR] e [CATALOG_ERROR] para localizar o provedor que falha quando há mais de um provedor em jogo.
Erros nativos de bibliotecas
Erros que se originam dentro de uma biblioteca subjacente (erros de carregamento de chart do SDK do Helm, erros do parser YAML do docker-compose, erros de E/S de arquivo por um caminho de origem ausente) são encapsulados com o prefixo de contexto por provedor e aparecem sob [TRANSLATION_ERROR] ou [CATALOG_ERROR], dependendo de terem ocorrido na síntese ou no carregamento do conteúdo do catálogo. A mensagem encapsulada da biblioteca preserva literalmente o diagnóstico da ferramenta original, para que os autores possam compará-lo com a própria documentação da ferramenta.
Referências cruzadas
fatal-halts.md— catálogo, erro por erro, de cada interrupção fatal com a mensagem pretendida e como corrigi-la.warnings.md— avisos não fatais que o compilador emite.vocabulary/validation-surface.md— as quatro camadas de validação de esquema e como as suas formas de erro interagem.