エラー変換の規律
Aggrega のコンパイルパイプラインは、スキーマバリデータ、リゾルバ、IR ビルダー、プロバイダ、Go テンプレートエンジン、そしてプロバイダがラップする基盤の YAML / Helm / docker-compose ライブラリなど、多くの箇所からエラーを出力します。CLI まで伝播したエラーは、最大 2 つの要素を示す角括弧付きのヘッドで始まります。1 つはカテゴリで、どの関心事を確認すべきか(ほとんどの値では、原因となったオーサリング箇所)を示します。もう 1 つはビルドを停止させた条件の短いコードです。その後にソースポインタとメッセージが続きます。条件をプラグインが発生させた場合、コードはそれを発生させたプラグインによって修飾されます。複数のプラグインが同じ条件を報告しうるためです。このページでは、作成者がエラーメッセージを直接解釈できるよう、その出力の形式を説明します。
エラーごとのカタログ(すべての致命的停止と修正方法のガイダンス)については、fatal-halts.md を参照してください。4 つのスキーマ検証レイヤーと、それぞれのエラー形式の相互作用については、vocabulary/validation-surface.md を参照してください。
エラーカテゴリ
カテゴリタグは、どの関心事を確認すべきかを示します。ほとんどのカテゴリは修正箇所となるオーサリング面を示し、残りは誰のオーサリングミスでもない関心事(アーティファクトの取得、ガバナンスの判定、信頼と署名)を示します。いずれの場合も、特定の条件を識別するのはヘッド内でカテゴリの横にある短いコードです。
[DEVELOPER_ERROR]— 失敗は Aggregate のオーサリングに帰属します。修正箇所は Aggregate の YAML、またはカタログのうち開発者が記述した部分(Component の値、usesソケット、Feature のアタッチメント)です。例: Aggregate 側の問題によるリゾルバの停止、Aggregate が記述した内容に対するセレクタおよびappliesToの違反。[OPS_ERROR]— 失敗はオペレーター自身のドキュメントである Release と Manifest に帰属します。修正箇所は Release の YAML(境界トポロジー、パラメーター値、Release レベルでの Feature のアタッチメント)、または Manifest の YAML(ある型をどの Recipe を通じてデプロイするか、およびその横に記述されたアノテーションバインディング)です。例: Release のスキーマ検証、境界パスのテンプレート評価、プロバイダー間でのsubDirectoryの衝突、Manifest のマッピングおよびアノテーションバインディングの拒否、Release が配線する接続や接続上で埋めるアタッチメントをルールが拒否する場合(ソケットのセレクタ、スロットのセレクタ、ソケットが必須と宣言するスロット)、Release だけがコンポーネントまたは境界にアタッチする Feature をルールが拒否する場合(その Feature のappliesTo、スロットのセレクタ、宣言されたスキーマ)。[CATALOG_ERROR]— 失敗はカタログエンティティ(Recipe、FeatureRecipe、Component、Feature、Plugin)に帰属します。修正箇所はカタログの内容です。例: Recipe の形状ルール、Workload のfeaturesSchemaのクロスチェック、カタログで記述されたテンプレートのパースエラー。[TRANSLATION_ERROR]— 失敗はプロバイダー側の合成(プロバイダープラグインが Workload、valuesMapping の出力、またはソース由来のオーバーレイをプロバイダーネイティブのアーティファクトに変換しようとする処理)に帰属します。修正箇所は通常、Workload のservices/containers/volumesの形状、Recipe のvaluesMappingテンプレートの出力、またはソースモードのオーバーレイ構造です。[FETCH_ERROR]— 失敗はレジストリまたはリモートソースからのピン留めされた依存関係の取得に帰属し、オーサリング面には帰属しません。修正は通常、運用上のものです。レジストリに認証する(docker login <registry>)、接続を復旧する、またはずれた、あるいは改ざんされたアーティファクトを再ピン留めする(aggrega pull --upgrade --release <release>)といった対応です。例: カタログエンティティやチャートがレジストリに見つからない、認証が必要または失敗した、ネットワークに到達できない、キャッシュされたアーティファクトのダイジェストがロックファイルと一致しない。取得エラーのメッセージには具体的な対処方法が含まれます。[POLICY_ERROR]— ガバナンス判定ロールにアタッチされたポリシープラグインによってビルドが拒否されました。これはオーサリング面の不備ではありません。入力は整形式ですが、プラグインが適用するガバナンスルール(コンプライアンス、FinOps、セキュリティ)を満たしていません。修正するには、記述した内容を適用されたポリシーに準拠させるか、ポリシーのアタッチメントを見直します。メッセージには拒否したプラグインの名前と、そのプラグインが提供したルールメッセージが含まれます。[TRUST_ERROR]— 信頼と署名のレイヤーが操作を拒否しました。このカテゴリはオーサリング面ではなく関心事を示し、横にある短いコードで区別できる 2 つの対処を含みます。信頼の設定が誤っている場合: 読み取れない信頼ポリシー、読み込めないピン留めされた信頼ルート、信頼されたアイデンティティを宣言していないキーレスポリシー、公開しようとしているアーティファクトの種類に署名を要求する署名ポリシー、または設定がもはやアタッチしていない判定アタッチメントに対して信頼済みとして記録されたプラグイン。アーティファクトが検証に失敗した場合: 信頼アンカーに対して検証できない署名、署名が必要な場所で署名を持たないアーティファクト、実在するが信頼されていない署名者による署名、または記録された信頼済みアイデンティティが解決結果と一致しなくなったプラグイン。前者の修正箇所は設定またはコミットされた信頼レコードです。後者はアーティファクトについての判断であり、レビュー済みのものを復元するか、変更内容をレビューして再記録します。
Feature のアタッチメントに関する検出結果は、それを記述したドキュメントに従う
Feature はどちらのドキュメントでもアタッチできます。Aggregate はコンポーネントまたはサブシステムに、Release はコンポーネントのエントリまたは境界にアタッチします。そのため、アタッチメントに関する検出結果のカテゴリは、到達先のコンポーネントではなく、アタッチメントが記述された場所から判断されます。検出結果は、そのドキュメント内でアタッチメントを記述した features: エントリに位置付けられ、そのドキュメントの作成者に帰属します。Release だけが行うアタッチメントは Release 自身のパスで [OPS_ERROR] として報告され、Aggregate が行うものは Aggregate のパスで [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.両方のドキュメントが 1 つのアタッチメントを記述する場合(Aggregate が Feature を指定し、Release がそのサイズを決める場合)、アタッチメント全体に関する検出結果は Feature が指定された場所、つまり Aggregate に位置付けられます。設定の一部に関する検出結果は、その部分が記述された場所に位置付けられます。values は開発者のもので Aggregate に、infra はオペレーターのもので Release にあります。アノテーション駆動の展開によって生成されたアタッチメントはどの features: エントリにも記述されていないため、それに関する検出結果は、コンポーネントを宣言するドキュメント内のコンポーネントに [DEVELOPER_ERROR] として位置付けられます。
空のままの必須スロットは、どのドキュメントも記述していない唯一のケースです。 指し示すアタッチメントがないため、検出結果は Aggregate 内のコンポーネントにとどまり [DEVELOPER_ERROR] として扱われます。どちらのドキュメントでもスロットを埋められるため、その対処方法は両方のドキュメントを示します。「Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it.(その名前で Feature を、Aggregate または Release 内で、コンポーネント上またはその上位のスコープにアタッチしてください。)」
エディターも同じ配置を読み取ります。Release に位置付けられた検出結果は Release のドキュメント上の、それを記述したキーに表示され、Aggregate のドキュメントにはまったく表示されません。Aggregate がインポートするモジュールのドキュメントに位置付けられた検出結果も、同じようにそのモジュールのドキュメントに表示されます。
出力の形式
出力される診断は、角括弧で囲まれたヘッドとソースポインタで始まり、メッセージはインデントされた独立した行に置かれます:
[CATEGORY SHORTCODE] <source> <message>ヘッドには 2 つのトークンがあり、それぞれ異なる問いに答えます。カテゴリは上記のいずれかで、どの関心事を確認すべきかを示します。ショートコードは文字 E と 4 桁の数字で、ビルドを停止させた正確な条件を示します。報告に引用する、検索に入力する、あるいは sentinels.md にあるすべての条件の表と照合するために使います。どちらも他方から導くことはできないため、両方が出力されます。また、[TRUST_ERROR] のように 1 つのカテゴリが複数の対処法を含む場合は、ショートコードによってどの対処法に該当するかがわかります。
プラグインが発生させたコードは、それを発生させたプラグインで修飾される
すべての短いコードは Aggrega が宣言する条件を指し、2 つの条件が 1 つのコードを共有することはありません。別の条件がすでに保持している番号で宣言された条件は、コンパイラが入力を読み取る前に拒否されます。プラグインは独自のコードを割り当てません。プラグインは失敗を報告するとき、Aggrega が宣言する条件の 1 つ(プラグインがどのように失敗したかを表すいくつかの汎用条件のいずれか、または該当する場合はより具体的な条件)を指定し、実際に何が起きたかを述べる文を提供します。そのため、2 つのプラグインが同じ短いコードを報告することがあり、その場合、両者は同じ条件を報告しています。
コードからは、どのプラグインがその条件に遭遇したかはわかりません。そのため、プラグインが発生させた条件を報告するヘッドは、コードの直前にプラグインの識別子を含みます:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>ショートコードは常に最後のセグメントです。最後の / の後にある、文字 E と 4 桁の数字です。プラグインの識別子には独自の区切り文字が含まれ、バージョンが含まれることもあるため、最初の / からではなく末尾から読むことで、どのヘッドからでもコードを取り出せます。最後のセグメントより前はすべてプラグインです。
最後のセグメントは、どのプラグインが発生させたかにかかわらず、他の短いコードと同じように調べられます。sentinels.md にあるすべての条件の表に掲載されており、aggrega explain で調べられます。引用するのは最後のセグメントだけにしてください。修飾子が示すのはどのプラグインがその条件に遭遇したかであり、それがどの条件かではありません。Aggrega が宣言していないコード(どの条件も保持していない番号、または廃止された番号)をプラグインが指定した場合、そのコードは出力されません。ビルドはそのプラグインで修飾された E0293 で停止し、そのメッセージはプラグインが提示したコードを引用し、前述の汎用条件を挙げ、プラグイン自身の文を保持します。
修飾のないショートコードを出力するヘッドは、Aggrega 自身が発生させた条件を報告しています。これには、プラグインが失敗し、独自の条件を示さなかった場合も含まれます。その場合、ビルドを停止させたのはコンパイラの汎用的なプラグイン失敗の条件であり、詳細はプラグインのメッセージに含まれます。
どちらのトークンも存在しないことがあり、存在しないものは省略される
診断が持たないトークンの代わりに何かが置かれることはありません。プレースホルダも、空の角括弧もありません。ヘッドが短くなる場合は 3 通りあり、それぞれが何かを示します:
- ショートコードがない場合。 失敗が Aggrega 自身の条件を示していません。多くの場合、コンパイラがラップしているライブラリが報告した障害です。ヘッドにはカテゴリだけが出力されるため、どの面を確認すべきかはわかります。
- カテゴリがない場合。 失敗に案内すべき関心事がないため、推測されることはありません。ヘッドにはショートコードだけが出力され、調べるのはそのコードです。これが生じる状況は 2 つあり、利用者にとっては同じであるため同じように読めます。どちらもどこを見るべきかは示さず、何が起きたかはコードが示します。1 つはコンパイラ自体の障害で、メッセージがそのことを述べ、報告を求めます。実際に起こるのは、コンパイラ自身が持つカタログのビュー同士が食い違うケースです。もう 1 つは、条件を示すものの、それを関心事に分類する面を一度も通過しなかった失敗で、コマンド境界で発生した拒否は通常この形になります。空白を埋めるためにカテゴリが作り出されることはありません。これは省略の制限ではなく、省略の目的です。カテゴリは「どの関心事を確認すべきか」に答えるものであり、問いに答えがない場所で与えられた答えは慎重な答えではなく誤った答えであり、真っ先にそれに従って行動されてしまいます。また、逆の推論は成り立たないことにも触れておきます。カテゴリを 持つ ヘッドが、常に自分が作成したものを指しているとは限りません。
[FETCH_ERROR]、[POLICY_ERROR]、[TRUST_ERROR]はいずれも作成面ではなく関心事を示すからです。 - どちらもない場合。 角括弧は完全に省略され、診断はメッセージだけになります。これは Aggrega 自身の条件を示さず、かつ 案内すべき関心事もない失敗です。引数を拒否するコマンド、読み込めないファイル、キャンセル、あるいはコンパイラがラップしているライブラリが報告した障害で、その下にこちらの条件が何もないものです。
sentinels.mdと照合するものはなく、メッセージが失敗の伝える内容のすべてです。
同じエラーを 1 行にまとめた形式は、端末ではなくログ出力に適したもので、カテゴリを含みショートコードを省きます:
[CATEGORY] <source>: <message>ヘッドにないカテゴリはここでも角括弧ごと省かれるため、この行が [] <source>: <message> になることはありません。1 行形式は、失敗が上位に伝わるにつれて外側のフレームに再びラップされるため、空のタグがあるとそのすべてに引き継がれてしまいます。
ソースは構造化されたポインタです。YAML の位置が得られる場合は通常 <file>:<line>:<column>、ファイル位置が当てはまらない場合は論理識別子(カタログエンティティ名、Release 名、境界パス)です。3 つ目の形式である <file> at <key> は、ポインタがドキュメントとその中の作成キーの両方を把握しているものの、バイト位置を持たない場合に現れます。ファイルは開く対象であり、キーは開いた後に確認する箇所です。メッセージは面ごとの診断です。
ビルドの 1 つのインスタンス(コンポーネント、モジュールが提供するコンポーネント、またはモジュールそのもの)に関する失敗は、位置の後に (instance <name>) という形でそのインスタンスを示します。したがって aggregate.yaml (instance shop) は、モジュール shop を宣言している Aggregate を表します。失敗に指し示すドキュメントがない場合、インスタンスは instance <name> として単独で表示されます。コンポーネント adminer のレンダリング中に失敗したプロバイダーは [TRANSLATION_ERROR E0082] instance adminer を出力し、その下の行に、失敗が示すドキュメントを含む失敗の残りの内容が続きます。名前は、Aggregate がそのコンポーネントを宣言するときの名前です。モジュールが提供するコンポーネントは、shop.cart のように、モジュールを経由するパスで命名されます。ファイルがあるべき場所にインスタンスが出力されることはないため、ソースポインタの先頭にあるのは常に開くことのできるドキュメントか、上記の論理識別子のいずれかです。
完成したグラフに対して評価されるルールは、この 3 つ目の形式で報告し、メッセージだけでは区別できない 2 つの検出結果を区別するのがキーです。この種のルールはインスタンスではなく、宣言している コンポーネント型を示すため、同じ型の 2 つのコンポーネントが同じルールに違反すると、同じファイルについて同じメッセージが出力されます:
[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")異なるのはキーだけであり、2 つのコンポーネントのどちらを編集すべきかを示すのはキーです。どちらの検出結果も同じ条件に 2 回該当したものであるため、同じショートコードを持ちます。ショートコードはルールを示し、キーは発生箇所を示します。
それを埋めるコンテキストを持つ失敗の場合、さらに 2 行がこの形式に加わります。失敗したテンプレート式と、失敗した時点でスコープ内にあったピラーのスナップショットです:
[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>expression: 行には、失敗を引き起こしたテンプレートの抜粋が含まれます。active pillars: ブロックには、失敗した時点で利用可能だったトップレベルのピラーキーが列挙されるため、作成者は何を参照できたかを確認できます。失敗がどちらも持たない場合、両方とも省略されます。
ネストしたコンテキストフレーム
エラーは CLI に届くまでに複数のサーフェスを通過することがよくあります。ロードフェーズが特定のエンティティの失敗をラップし、そのエンティティの失敗がさらにルールを説明するセンチネルをラップします。このようなチェーン内のカテゴリ付きフレームはすべて描画されます。最も外側のフレームは上記の形式のヘッドとして、ネストした各フレームはインデントされた caused by: の継続行として描画され、それぞれ独自のカテゴリタグ、ソースポインタ、メッセージを持ちます。最も内側のファイルを指すフレームは常に表示されます。
[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")短いコードを持つのはヘッドだけで、継続行はカテゴリのみを持ちます。 条件は、読み手が失敗に出会う箇所で一度だけ名指しされます。caused by: マーカーの下にあるフレームは同じ失敗をより内側から見たものなので、各フレームでその識別子を繰り返しても、事実は増えず行が増えるだけです。note: ブロックは継続行ではなく、このルールには従いません。これは同じ条件をより内側から見たものではなく、他のドキュメントの条件を報告するものです。詳しくは後述のセクションで説明します。ヘッドが出力するコードはチェーンが名指しするコード(この例では最下部のルール)なので、最上部のフェーズコンテキストのフレームでも、その下にある条件を特定できます。
上から順に読みます。失敗したフェーズ、次にそれを引き起こしたエンティティ(ファイルパス付き)、そして違反したルールです。親に何も付け加えないネストしたフレーム(同じカテゴリ、同じソース、親がすでに含んでいるメッセージ)は繰り返されず重複排除されます。また、末端の説明は、その上のフレームがまだそのテキストを含んでいない場合にのみ描画されます。
失敗が外に出るまでにより多くのサーフェスを通過するほどチェーンは深くなり、このルールはどの深さでも成り立ちます。Recipe が合成した Workload 内で拒否されたテンプレートは、3 つのサーフェスを通過します。描画中のノード、Recipe のテンプレートサーフェス、そしてテンプレート自体です。
[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)前と同じく上から順に読み、深さが増えたことで見えてくる 3 つの点に注目してください。短いコードはヘッドに一度だけ現れます。後に続く継続行がいくつあっても同じです。最も内側のフレームに条件自体の文があります。そのため、最も深い行が照合に使う行であり、何を変更すべきかを示す行でもあります。そして ソースポインタのないフレームはカテゴリのみを出力します。上の中間のフレームは、失敗したサーフェスをメッセージ内で名指ししています。そのサーフェスはファイルではなくテンプレートであり、指し示す位置がないためです。
失敗があるフレームの下で分岐する場合(停止する前に複数の独立した違反を収集したフェーズなど)、継続行は件数を持ち、収集されたすべての失敗がその下に描画されます。各失敗は、後述のマルチエラーチェーンと同じ --- 区切り線で区切られます。
[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件数の下に収集された失敗も継続行なので、どれもヘッドの短いコードを繰り返しません。そのおかげで、12 件の違反の分岐でも同じ識別子が 12 回出力されることはありません。
区切りの文法は全体を通じて 1 つです。兄弟関係にある失敗の間には ---、ネストしたコンテキストフレームの間には caused by: を使います。
拒否されたカタログファイルと、それが説明する失敗
Release が依存するものを解決するためのカタログ読み込みは、意図的に寛容になっています。読み取れないファイル、または解析もインデックス化もできない Aggrega ドキュメントは、読み込み全体を中断させるのではなく、拒否されて記録されます。これにより、Release が一切触れない壊れたエンティティが、無関係なビルドを失敗させることがなくなります。
その結果、拒否されたファイルはカタログから黙って欠落します。そして Release がそのファイルに実際に到達する場合、失敗するのは、そのファイルが宣言していたものへの参照を解決しようとする試みです。この失敗は拒否そのものではなく拒否の結果であるため、レポートは拒否を正確に特定できる場合には常に、両者を因果の順に並べます。
[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"拒否が先頭に来て、独自のカテゴリと独自の短いコードを持ちます。これは、対処できる対象を示すのが拒否だからです。修正すべきなのは Recipe に欠けている implements: であり、レジストリで参照がどのように検索されるかとは関係ありません。解決の失敗もその下に引き続き報告されます。そのドキュメントがそもそもなぜ必要だったのかを示すのが、この失敗だからです。
拒否が先頭に来るのは、失敗した参照が示す識別情報を宣言している拒否ファイルがちょうど 1 つだけの場合に限られます。 照合は各ドキュメントが自身について宣言する識別情報、つまり kind、名前、バージョン、そして recipe の場合はそのスコープを定める spec.capability に対して行われます。したがって、参照が求めるものを宣言している拒否ファイルは、その参照が解決されるはずだったファイルです。ここから 2 つのことが導かれます。バージョンではなくバージョンの範囲を指定する参照は単一のドキュメントを示さないため、何も特定しません。また、ヘッダーを読み取れないほど不正な形式のドキュメントは識別情報をまったく宣言しないため、何かの原因として示されることはありません。
その識別情報を宣言する拒否ファイルが存在しない場合、または複数存在する場合、レポートは拒否の記録がない場合と同じになります。失敗が先頭に来て、すべての拒否がその下に列挙され、判断を委ねます。誤ったファイルを原因として示すことは、何も示さないことよりも悪い結果になります。それに基づいて行動してしまうからです。
[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この 2 つ目の形式については、知っておくべき点がいくつかあります。それぞれが、このブロックを見たときに生じるはずの疑問に答えるものです。
先頭は拒否ではなく失敗を示します。 最上部の短いコードは解決の失敗が発生させたものです。ここで先頭に来るのはその失敗であり、どの拒否ファイルも特定されなかったため、いずれも先頭行にはなりません。横にカテゴリが付かないのは、この経路ではどこもその失敗を関心事の下に分類しなかったためです。各拒否自身の先頭は、その下のそれぞれのエントリにあり、そこで読み取ります。
問題となった拒否だけでなく、すべての拒否が列挙されます。 この形式になるということは、記録から 1 つを特定できなかったことを意味します。そのため note は推測する代わりに区別を示します。この Release のクロージャ外にある拒否は許容されており、失敗の原因にはなり得ません。したがって、Release が到達するものを示す拒否だけが、失敗を説明するエントリとして残ります。各エントリを、Release が実際に使用しているものと照らし合わせて読んでください。
各エントリは、独自のカテゴリと独自の短いコードという、角括弧で囲まれた独自の先頭を持ちます。 診断の先頭より下に短いコードが現れるのはここだけです。これは前述の継続行の規則の例外ではなく、その帰結です。note: の下のエントリは、同じ失敗をより内側から見たものではなく、別のドキュメントが発生させた別の状態です。その状態を示すことで、拒否を調べてファイルを修正できます。それこそが、このブロックが可能にするための操作です。
ヘッダーの形式が不正すぎて、宣言している ID を復元できない拒否されたファイルは、パスのみで一覧に示されます。 それが、何も中をのぞけなかったドキュメントの正直な読み方であり、パスがあればファイルを開くには十分です。種類すら読み取れないほど形式が不正なファイル(たとえば YAML として解析できないもの)は、Aggrega の apiVersion を宣言している場合、つまりインデントなしで apiVersion: から始まり、値が aggrega.ai/ で始まる行がある場合に、この形で一覧に示され、パーサー自身の理由(その行と、パーサーがそこで期待していたもの)が添えられます。別の apiVersion を宣言している、または何も宣言していない YAML ファイルは Aggrega ドキュメントではなく(たとえばチャートのテンプレートや、エンティティの隣に置かれた設定ファイル)、どれほど形式が不正でも一覧に示されることはありません。
どのカタログも保持しない種類を宣言しているファイルは、それが失敗の説明になる場合にのみ示されます。 Aggrega の apiVersion と、どのカタログも保持しない kind(たとえば綴りを誤った Componnent)を宣言しているドキュメントは、すべての読み込みで読み飛ばされるため、拒否には当たらず、拒否の一覧にも挙げられません。失敗した参照が求める名前がそのファイルの宣言する名前であり、参照がバージョンを指定している場合はそのバージョンも一致するとき、レポートは、参照がどの種類として収集されたかにかかわらず、失敗の下に独立した注記としてそのファイルを示します。これは以下に挙げるすべてのサーフェスで行われ、aggrega build では既存のロックファイルを読む場合も、先にロックファイルを埋める場合も同様です:
[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失敗が先頭に来ることは変わりません。ファイルが宣言する種類は何のアイデンティティも示さないため、そのファイルがレポートの冒頭に置かれる拒否として特定されることはありません。ローカルのエンティティがどこから読み込まれるかの説明はそのレポートから省かれます。そのファイルはすでにカタログが読み込む場所にあり、移動しても役に立たないからです。どのカタログも保持しない種類で別の名前を宣言しているファイルは、この失敗について何も説明しないため、言及されません。メッセージが 1 行である aggrega serve は、その行に同じ注記を含め(note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: の後にそのファイルの拒否が続きます)、そのようなファイルを読み込み時にスキップされたファイルの一覧に挙げることはありません。aggrega mcp の describe ツールも、Release の観点で名前を問われた場合、その説明の代わりにそのファイルを示します。カタログ全体を対象とする aggrega validate と aggrega lint は、何かがそのファイルに到達するかどうかにかかわらず、そのようなファイルをすべて報告します。fatal-halts.md の §「A catalog document declares a kind a catalog does not hold (カタログドキュメントが、カタログが保持しない種類を宣言している)」を参照してください。
どちらの形式になっても、失敗は独自の識別情報を保持します。 note は失敗の上に描画されるのではなく失敗に追加されるものであり、拒否を先頭にすることで変わるのは最初に読む内容だけです。そのため、失敗が発生させた状態はどちらの場合も損なわれません。短いコードは引き続き解決でき、状態を照合するツールも引き続き一致します。
拒否されたドキュメント自体がコマンドの報告対象である場合、拒否は 1 回だけ示されます。 aggrega inspect <name> はカタログを厳格に読み込むため、読み込みが拒否したドキュメントはコマンドを停止させます。出力されるのは、そのドキュメントの拒否を単一の診断として示したものです。先頭には拒否のカテゴリと短いコードがあり、ソースとしてドキュメントが示され、その下にドキュメントの問題点が示されます。スキーマ違反の場合は、違反したキーとその行と列、そしてアドバイスです。これを発生させた読み込みは、走査していたディレクトリとファイルを読み取ったステップを経由していますが、それらは独自のフレームとしては出力されません。いずれも事実を追加せずに同じドキュメントを再び示すだけだからです。aggrega serve は、拒否されたドキュメントが宣言している名前が何を指すかを問われると、同じ拒否を同じ文言で 1 行で答え、その後にファイルが読み込み時にスキップされたという note を続けます。前述のとおり、拒否の状態はどちらの場合も照合可能なままです。
どちらの形式も、その解決が実行される場所であればどこでも届きます。 aggrega build、aggrega pull、aggrega validate --release、aggrega inspect --closure はターミナルでこれらを出力し、implements のターゲットが見つからない 1 つの Recipe に対する aggrega validate も同様です。aggrega mcp を通じて接続された AI アシスタントは build ツールと validate ツールから同じ内容を受け取り、拒否されたファイルが宣言するエンティティを catalog:// で読み取った場合には、先頭に来る拒否を 1 行で受け取ります。どのサーフェスから問い合わせても、開くよう案内されるファイルは変わりません。HTTP 経由で aggrega mcp にアクセスする呼び出し元にはワークスペースルートからの相対パスで伝えられ、そのサーバーが提供するワークスペース外のファイルは伝えられません。また、拒否が先頭に来る場合、回答が示すオーサリング契約は、拒否されたドキュメントが宣言する kind のものであり、失敗した参照の kind のものではありません。
ドキュメントエンベロープの失敗クラス
すべてのエンティティドキュメント(カタログエンティティ、Aggregates、Manifests、Releases)は、読み込まれる際、型付きの解析より前に、その種別の公開 JSON Schema に照らして検証されます。エンベロープに違反するドキュメント(未知のキー、必須フィールドの欠落、形の誤った値、Release の values: のような禁止された構文)は明示的に停止し、診断を出力します。この診断は、まず条件を示し、次にエンティティ種別とファイル、続いて問題のある各キーまたは形とその行と列、最後に対処方法を示します。
[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診断は条件で始まり、種別とファイルを示し、対処方法で終わります。その間にある各違反は line:column のみを持ちます。ヘッドですでにファイルが示されているためです。問題のある各キーは、それを含むブロックの位置ではなく、そのキー自身の位置で報告されるため、行と列は変更すべきキーを指します。その位置の形がスキーマ内の再利用可能な定義に由来する場合、診断は against という語の後にその定義を示します(上の例では against /$defs/boundary)。これにより、キーがどの契約に照らして測られたかが明確になり、その定義が記述したキーパスのもう一つのステップとして読まれることはありません。複数の違反を持つドキュメントは、それぞれをその位置ごとにキー順で列挙し、報告は 4 件で止まり、残りの件数を示します。
位置がどこを指すかについて、知っておくと役立つ点が 2 つあります。どちらも意外なものではなく、有用なものです。
- 欠落している必須キーには、それ自身の位置がありません。定義上、ドキュメントに存在しないためです。代わりに違反は、欠落したエントリが属する外側のキーを指します。したがって
spec.capability: missing required propertyはspec:を指し、そこが追加すべき場所です。 - 名前自体にドットを含むキー(すべての
component.aggrega.ai/…ラベルとfeatures.aggrega.ai/…アノテーション)は、エントリ自体ではなく、それを保持するブロックで報告されます。ドットはドキュメント内へ下るステップとして読まれるためです。ラベルに対する違反はlabels:を指します。
違反が、ドキュメントのどこにも存在しないキー(たとえば metadata: ブロック全体が欠けている場合)を示すときは、位置は推測されずに省略され、違反はキーパスとメッセージのみで表示されます。信頼できない位置は、位置がないよりも悪いためです。
カテゴリはオーサリング面に従います。カタログエンティティには [CATALOG_ERROR]、Aggregates には [DEVELOPER_ERROR]、Releases と Manifests には [OPS_ERROR] です。同じゲートは、エンティティを読み込むすべての面(aggrega build、aggrega lint、aggrega validate、および aggrega serve が公開するエディタ診断)で実行されます。そのため、不要なキーや綴りの誤ったキーは、黙って捨てられるのではなく、ドキュメントが最初に読まれた場所で拒否されます。これらの各面は位置を同じ方法で解決するため、同じキーを指します。また、各面は条件の文を条件自体から読み取ります。エディタが下線を引く行はターミナルが示す行であり、エディタのエントリが始まる文はターミナルが始まる文と同じです。2 つの面が共有しないのはメッセージ全体であり、これは意図的なものです。ターミナルはすべての検出結果を 1 つのヘッダーの下にまとめ、そのパスに対する助言で締めくくります。一方、エディタは検出結果ごとに 1 つのエントリを、それぞれのキーの位置に出力し、すでに関連付けられているファイルも、下線ごとに繰り返すことになる助言も繰り返しません。したがって、一致する部分は、条件を見分けるための部分です。
複数エラーのチェーン
1 回のコンパイルで互いに独立した複数の違反が検出された場合(最も多いのは静的解析中で、ビルドを停止する前にすべてのセレクターと appliesTo の違反が収集されます)、エラーは 1 つのチェーンに結合されます。CLI はチェーンをたどり、各サブエラーを個別に、水平線の行で区切って表示します:
[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.--- の区切りはそのままの文字列です。読み手や下流のツールはこれで分割して、結合されたエラーを列挙できます。各サブエラーは隣のエラーの詳細ではなくそれ自体が 1 つの失敗であるため、それぞれが独自のヘッドを持ちます。つまり、欠落したトークンに関するセクションで説明するとおり、固有のカテゴリと固有の短いコードを、それぞれ存在する場合に持ちます。上の例のように、1 つのルールに対する 2 つの違反は同じ短いコードを示し、異なるルールに対する 2 つの違反は異なるコードを示します。
エラーを最初から最後まで読む
ほとんどのオーサリングの場面では、カテゴリのプレフィックスとソースポインタを組み合わせることで、何を修正すべきかを特定できます。
| カテゴリ | 修正箇所 | 発生箇所の例 |
|---|---|---|
[DEVELOPER_ERROR] | Aggregate YAML | Aggregate が記述した内容に対するセレクタ / appliesTo の違反、Aggregate 側の uses ソケットの不一致、開発者のオーサリングに起因するリゾルバの停止。 |
[OPS_ERROR] | Release YAML / Manifest YAML | 境界パステンプレートがサポートされていないフィールドを参照している、subDirectory がパスの衝突を引き起こしている、Release のオーサリングに起因するリゾルバの停止、Release が配線する接続、または接続上で Release が埋めるアタッチメントが、ソケットまたはスロットのルールによって拒否された、Release のみがコンポーネントまたは境界にアタッチする Feature が、Feature またはスロットのルールによって拒否された、Manifest のマッピングまたはアノテーションのバインディングが拒否された。 |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Recipe の形状ルール、executionScope: boundary を指定した FeatureRecipe のテンプレートがコンポーネント単位専用のフィールドを参照している、Workload の featuresSchema のクロスチェックが失敗した。 |
[TRANSLATION_ERROR] | Workload / valuesMapping の出力 / ソースオーバーレイ | Helm のプローブポートの解決、境界をまたいだ compose のサービス名の衝突、2 つの compose コントリビューターが同じトップレベルの volume 名または config 名を矛盾する本体で宣言している、helm-chart アンブレラでのチャート名の不一致。 |
[FETCH_ERROR] | レジストリ / リモートソースの取得(運用上の問題であり、オーサリングの問題ではありません) | レジストリにアーティファクトが見つからない、認証が必要、ネットワークに到達できない、キャッシュされたダイジェストがロックファイルと一致しない。修正方法:認証する、接続を回復する、または aggrega pull --upgrade --release <release> を実行します。 |
[POLICY_ERROR] | ポリシープラグイン(ガバナンスルール) | ガバナンスの判定ロールにアタッチされたポリシープラグインが、自身が適用するルールに照らして、組み立てられたビルドを拒否しました。修正方法:適用されているポリシーを満たすか、アタッチメントを見直します。 |
[TRUST_ERROR] | トラスト設定、またはアーティファクト自体の署名(関心事であり、オーサリングの対象ではありません) | 読み取れないトラストポリシーまたは固定されたトラストルート、信頼済みアイデンティティを宣言していないキーレスポリシー、公開される種類に署名を要求する署名ポリシー、設定がもはやアタッチしていない、記録済みの判定アタッチメントゲート。または、検証できない署名、署名が必要な場面で署名を持たないアーティファクト、信頼されていない署名者、記録された信頼済みアイデンティティがもはや一致しないプラグイン。修正方法:設定またはコミット済みのトラストレコードを修正するか、アーティファクトについて判断します。どちらかはショートコードが示します。 |
プロバイダごとのコンテキストプレフィックス(helm: node "<id>": ...、compose: node "<id>": ...)は、[TRANSLATION_ERROR] および [CATALOG_ERROR] の出力のメッセージ部分に現れ、複数のプロバイダが関与している場合に失敗したプロバイダを特定します。
ライブラリ固有のエラー
基盤となるライブラリの内部で発生したエラー(Helm SDK のチャート読み込みエラー、docker-compose の YAML パーサーエラー、存在しないソースパスによるファイル I/O エラー)は、プロバイダーごとのコンテキスト接頭辞でラップされ、合成中に発生したかカタログコンテンツの読み込み中に発生したかに応じて、[TRANSLATION_ERROR] または [CATALOG_ERROR] として表面化します。ラップされたライブラリのメッセージは元のツールの診断をそのまま保持するため、作成者はそれをツール自身のドキュメントと照合できます。
相互参照
fatal-halts.md— すべての致命的な停止について、想定されるメッセージと修正方法をエラーごとにまとめたカタログです。warnings.md— コンパイラが出力する、致命的ではない注意喚起です。vocabulary/validation-surface.md— 4 つのスキーマ検証レイヤーと、それぞれのエラーの形がどのように相互作用するかを説明します。