Disiplin penerjemahan galat
Pipeline kompilasi Aggrega menghasilkan galat dari banyak permukaan — validator skema, resolver, pembangun IR, para provider, mesin templat Go, serta pustaka YAML / Helm / docker-compose yang mendasarinya dan dibungkus oleh para provider. Galat yang naik hingga ke CLI diawali dengan kepala dalam tanda kurung siku yang menyebutkan hingga dua hal — sebuah kategori, yang menunjukkan aspek mana yang perlu diperiksa (untuk sebagian besar nilai, permukaan penulisan yang bermasalah), dan kode singkat dari kondisi yang menghentikan build — diikuti oleh penunjuk sumber dan sebuah pesan. Jika sebuah plugin yang memunculkan kondisi tersebut, kode tersebut dikualifikasi oleh plugin yang memunculkannya, karena lebih dari satu plugin dapat melaporkan kondisi yang sama. Halaman ini mendokumentasikan bentuk keluaran tersebut agar penulis dapat memahami pesan galat secara langsung.
Untuk katalog per galat (setiap penghentian fatal beserta panduan cara memperbaikinya), lihat fatal-halts.md. Untuk keempat lapisan validasi skema dan bagaimana bentuk galatnya saling berinteraksi, lihat vocabulary/validation-surface.md.
Kategori galat
Tag kategori menunjukkan aspek mana yang perlu diperiksa. Sebagian besar tag menyebut permukaan penulisan tempat perbaikan berada; sisanya menyebut aspek yang bukan kesalahan penulisan siapa pun — pengambilan artefak, putusan tata kelola, atau kepercayaan dan penandatanganan — dan kode pendek pada kepala di samping kategori itulah yang mengidentifikasi kondisi spesifiknya dalam setiap kasus:
[DEVELOPER_ERROR]— kegagalan melekat pada penulisan Aggregate. Perbaikannya ada di YAML Aggregate atau di bagian katalog yang ditulis pengembang (nilai Component, soketuses, lampiran Feature). Contoh permukaan: penghentian resolver karena masalah di sisi Aggregate; pelanggaran selektor danappliesTopada apa yang ditulis Aggregate.[OPS_ERROR]— kegagalan melekat pada dokumen milik operator sendiri, yaitu Release dan Manifest. Perbaikannya ada di YAML Release (topologi batas, nilai parameter, lampiran Feature pada tingkat Release) atau di YAML Manifest (Recipe mana yang digunakan untuk men-deploy suatu tipe, dan pengikatan anotasi yang ditulis di sampingnya). Contoh permukaan: validasi skema Release; evaluasi templat jalur batas; tabrakansubDirectoryantar-provider; penolakan pemetaan Manifest dan pengikatan anotasi; aturan yang menolak koneksi yang dihubungkan oleh Release, atau lampiran yang diisinya pada suatu koneksi — selektor soket, selektor slot, slot yang dinyatakan wajib oleh soket; aturan yang menolak Feature yang hanya dilampirkan oleh Release, pada komponen atau pada batas —appliesTomilik Feature tersebut, selektor slot, skema yang dideklarasikannya.[CATALOG_ERROR]— kegagalan melekat pada entitas katalog (Recipe, FeatureRecipe, Component, Feature, Plugin). Perbaikannya ada di konten katalog. Contoh permukaan: aturan bentuk Recipe; pemeriksaan silangfeaturesSchemapada Workload; galat parsing templat pada templat yang ditulis di katalog.[TRANSLATION_ERROR]— kegagalan melekat pada sintesis di sisi provider (plugin provider yang mencoba menerjemahkan Workload, keluaran valuesMapping, atau overlay bersumber menjadi artefak native provider). Perbaikannya biasanya ada pada bentukservices/containers/volumesmilik Workload, keluaran templatvaluesMappingmilik Recipe, atau struktur overlay mode sumber.[FETCH_ERROR]— kegagalan melekat pada pengambilan dependensi yang dipin dari registry atau sumber jarak jauh, bukan pada permukaan penulisan mana pun. Perbaikannya biasanya bersifat operasional: lakukan autentikasi ke registry (docker login <registry>), pulihkan konektivitas, atau pin ulang artefak yang telah bergeser atau dirusak (aggrega pull --upgrade --release <release>). Contoh permukaan: entitas katalog atau chart tidak ditemukan di registry; autentikasi diperlukan atau gagal; jaringan tidak dapat dijangkau; digest artefak dalam cache tidak cocok dengan lockfile. Galat pengambilan membawa petunjuk perbaikan yang konkret dalam pesannya.[POLICY_ERROR]— build ditolak oleh plugin kebijakan yang dilampirkan pada peran putusan tata kelola. Ini bukan kesalahan permukaan penulisan: masukannya terbentuk dengan baik, tetapi gagal memenuhi aturan tata kelola (kepatuhan, FinOps, atau keamanan) yang diberlakukan plugin tersebut. Perbaikannya adalah menyesuaikan apa yang Anda tulis agar mematuhi kebijakan yang diberlakukan, atau meninjau ulang lampiran kebijakan tersebut. Pesannya menyebut plugin yang menolak dan membawa pesan aturan yang diberikannya.[TRUST_ERROR]— lapisan kepercayaan dan penandatanganan menolak operasi. Kategori ini menyebut suatu aspek, bukan permukaan penulisan, dan mencakup dua jenis perbaikan yang dapat Anda bedakan dari kode pendek di sampingnya. Konfigurasi kepercayaan Anda salah: kebijakan kepercayaan yang tidak dapat dibaca, akar kepercayaan yang dipin tetapi tidak dapat dimuat, kebijakan keyless yang tidak mendeklarasikan identitas tepercaya, kebijakan penandatanganan yang mewajibkan tanda tangan untuk jenis artefak yang sedang Anda publikasikan, atau plugin yang tercatat sebagai tepercaya untuk lampiran putusan yang tidak lagi dilampirkan oleh konfigurasi Anda. Artefak ini gagal verifikasi: tanda tangan yang tidak terverifikasi terhadap jangkar kepercayaan, artefak tanpa tanda tangan padahal tanda tangan diwajibkan, tanda tangan dari penanda tangan yang nyata tetapi tidak tepercaya, atau plugin yang identitas tepercayanya yang tercatat tidak lagi cocok dengan hasil resolusinya. Perbaikan pada kasus pertama ada di konfigurasi Anda atau di catatan kepercayaan yang di-commit; pada kasus kedua, perbaikannya berupa keputusan tentang artefak tersebut — pulihkan artefak yang telah ditinjau, atau tinjau dan catat ulang apa yang berubah.
Temuan tentang lampiran Feature mengikuti dokumen yang menulisnya
Feature dapat dilampirkan di salah satu dari kedua dokumen — Aggregate melampirkannya pada komponen atau subsistem, Release pada entrinya untuk suatu komponen atau pada batas — sehingga kategori temuan tentang suatu lampiran dibaca dari tempat lampiran itu ditulis, bukan dari komponen yang dicapainya. Temuan diposisikan pada entri features: yang menulis lampiran tersebut, di dokumen itu, dan dicatat atas nama penulis dokumen itu: lampiran yang hanya dibuat oleh Release dilaporkan pada jalur milik Release sendiri sebagai [OPS_ERROR], dan lampiran yang dibuat oleh Aggregate dilaporkan pada jalur Aggregate sebagai [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.Jika kedua dokumen menulis satu lampiran — Aggregate menyebut Feature-nya, Release menentukan ukurannya — temuan tentang lampiran secara keseluruhan diposisikan di tempat Feature-nya disebut, yaitu Aggregate. Temuan tentang satu bagian konfigurasinya diposisikan di tempat bagian itu ditulis: values miliknya adalah milik pengembang, di Aggregate, dan infra miliknya adalah milik operator, di Release. Lampiran yang dihasilkan oleh ekspansi berbasis anotasi tidak ditulis oleh entri features: mana pun, sehingga temuan tentangnya diposisikan pada komponen, di dokumen yang mendeklarasikan komponen tersebut, sebagai [DEVELOPER_ERROR].
Slot wajib yang dibiarkan kosong adalah satu-satunya kasus yang tidak ditulis oleh dokumen mana pun. Tidak ada lampiran yang dapat ditunjuk, sehingga temuan tetap berada pada komponen di Aggregate dan dicatat sebagai [DEVELOPER_ERROR], dan perbaikannya menyebut kedua dokumen, karena salah satunya dapat mengisi slot tersebut: “Lampirkan Feature dengan nama itu, di Aggregate atau di Release, pada komponen atau pada cakupan di atasnya.”
Editor membaca penempatan yang sama: temuan yang diposisikan di Release ditampilkan pada dokumen Release, pada kunci yang menulisnya, dan sama sekali tidak ditampilkan pada dokumen Aggregate; temuan yang diposisikan di dokumen sebuah modul yang diimpor Aggregate ditampilkan pada dokumen modul tersebut dengan cara yang sama.
Bentuk keluaran
Diagnostik yang dicetak diawali dengan kepala berkurung siku dan penunjuk sumber, lalu menempatkan pesan pada barisnya sendiri yang menjorok:
[CATEGORY SHORTCODE] <source> <message>Kepala tersebut memuat dua token, dan keduanya menjawab pertanyaan yang berbeda. Kategori adalah salah satu dari yang disebutkan di atas dan menunjukkan perhatian mana yang perlu diperiksa. Kode pendek adalah huruf E diikuti empat digit, dan kode ini menamai kondisi persis yang menghentikan build: kutip kode ini dalam laporan, ketikkan dalam pencarian, atau cocokkan dengan tabel semua kondisi di sentinels.md. Keduanya tidak dapat diturunkan satu dari yang lain, itulah sebabnya keduanya dicetak — dan bila satu kategori mencakup lebih dari satu perbaikan, seperti [TRUST_ERROR], kode pendeklah yang memberi tahu Anda perbaikan mana yang Anda hadapi.
Kode yang dimunculkan oleh plugin dikualifikasi oleh plugin yang memunculkannya
Setiap kode singkat menamai kondisi yang dideklarasikan Aggrega, dan tidak ada dua kondisi yang berbagi satu kode: kondisi yang dideklarasikan di bawah nomor yang sudah dipegang kondisi lain ditolak sebelum compiler membaca input apa pun. Plugin tidak mengalokasikan kodenya sendiri. Ketika melaporkan kegagalan, plugin menyebut salah satu kondisi yang dideklarasikan Aggrega — salah satu dari beberapa kondisi umum yang menjelaskan bagaimana sebuah plugin gagal, atau kondisi yang lebih spesifik jika ada yang sesuai — dan menyediakan kalimat yang menyatakan apa yang sebenarnya terjadi. Jadi dua plugin dapat melaporkan kode singkat yang sama, dan ketika itu terjadi, keduanya melaporkan kondisi yang sama.
Yang tidak dapat dinyatakan oleh kode adalah plugin mana yang mengalami kondisi tersebut, dan kepala yang melaporkan kondisi yang dimunculkan oleh plugin memuat identitas plugin tepat sebelum kodenya:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>Kode pendek selalu merupakan segmen terakhir — huruf E dan empat digit, setelah / terakhir. Identitas plugin memuat pemisahnya sendiri, dan dapat memuat versi, sehingga membaca dari akhir alih-alih dari / pertama itulah yang membuat kode dapat diambil dari kepala mana pun. Semua yang berada sebelum segmen terakhir itu adalah plugin.
Segmen terakhir diselesaikan seperti kode singkat lainnya, plugin mana pun yang memunculkannya: tabel semua kondisi di sentinels.md mencantumkannya, dan aggrega explain menjelaskannya. Kutip segmen terakhir saja — kualifikasi tersebut menyatakan plugin mana yang mengalami kondisi itu, bukan kondisi yang mana. Plugin yang menyebut kode yang tidak dideklarasikan Aggrega — nomor yang tidak dipegang kondisi apa pun, atau yang sudah dipensiunkan — tidak mendapatkan kode itu tercetak: build berhenti pada E0293, dikualifikasi oleh plugin tersebut, dan pesannya mengutip kode yang diajukan plugin, menyebut kondisi-kondisi umum tersebut, dan mempertahankan kalimat milik plugin itu sendiri.
Kepala yang mencetak kode pendek tanpa kualifikasi melaporkan kondisi yang dimunculkan oleh Aggrega sendiri, termasuk kasus ketika suatu plugin gagal tanpa menamai kondisinya sendiri. Dalam kasus itu, kondisi kegagalan plugin generik milik kompilerlah yang menghentikan build, dan pesan plugin memuat detailnya.
Salah satu token dapat tidak ada, dan token yang tidak ada dihilangkan
Tidak ada apa pun yang menggantikan token yang tidak dimiliki diagnostik — tidak ada placeholder, tidak ada kurung siku kosong. Ada tiga cara sebuah kepala dapat menjadi lebih pendek, dan masing-masing memberi tahu Anda sesuatu:
- Tanpa kode pendek. Kegagalan tidak menamai kondisi milik Aggrega sendiri — paling sering berupa kesalahan yang dilaporkan oleh pustaka yang dibungkus kompiler. Kepala hanya mencetak kategori, sehingga Anda tetap tahu permukaan mana yang perlu diperiksa.
- Tanpa kategori. Kegagalan tidak memiliki perhatian yang dapat dirujukkan kepada Anda, sehingga tidak ada yang ditebak. Kepala hanya mencetak kode pendek, dan kode itulah yang Anda cari artinya. Dua situasi menghasilkannya, dan keduanya terbaca serupa karena bagi keperluan Anda keduanya memang serupa — tidak satu pun memberi tahu di mana harus melihat, dan kodenya memberi tahu apa yang terjadi. Yang pertama adalah kesalahan pada kompiler itu sendiri, yang pesannya menyatakan demikian dan meminta Anda melaporkannya; kasus yang muncul adalah ketika pandangan-pandangan kompiler sendiri atas katalog saling tidak sesuai. Yang kedua adalah kegagalan yang menamai suatu kondisi tetapi tidak pernah melewati permukaan yang menggolongkannya ke suatu perhatian, yang merupakan bentuk umum untuk penolakan yang dimunculkan di batas perintah. Kategori tidak pernah dikarang untuk mengisi kekosongan, dan justru itulah tujuan penghilangan tersebut, bukan keterbatasannya: kategori menjawab “perhatian mana yang perlu saya periksa”, dan jawaban yang diberikan ketika pertanyaannya tidak memiliki jawaban bukanlah jawaban yang hati-hati melainkan jawaban yang salah, yang akan ditindaklanjuti lebih dulu. Perlu juga dikatakan bahwa kesimpulan sebaliknya tidak berlaku: kepala yang memang memuat kategori tidak selalu menunjuk sesuatu yang Anda tulis, karena
[FETCH_ERROR],[POLICY_ERROR], dan[TRUST_ERROR]masing-masing menamai suatu perhatian, bukan permukaan penulisan. - Tidak keduanya. Kurung siku dihilangkan sepenuhnya dan diagnostik hanya berupa pesannya. Ini adalah kegagalan yang tidak menamai kondisi milik Aggrega sendiri dan tidak memiliki perhatian yang dapat dirujukkan kepada Anda: perintah yang menolak argumennya, berkas yang tidak dapat dibacanya, pembatalan, atau kesalahan yang dilaporkan oleh pustaka yang dibungkus kompiler tanpa kondisi milik kami di baliknya. Tidak ada yang perlu dicocokkan dengan
sentinels.md, dan pesan itulah keseluruhan yang dapat disampaikan kegagalan tersebut.
Galat yang sama yang diringkas menjadi satu baris, bentuk yang cocok untuk keluaran log alih-alih terminal, memuat kategori dan menghilangkan kode pendek:
[CATEGORY] <source>: <message>Kategori yang tidak ada di kepala juga tidak ada di sini, termasuk kurung sikunya, sehingga baris ini tidak pernah berupa [] <source>: <message>. Bentuk satu baris dibungkus ulang ke dalam bingkai-bingkai pembungkus saat kegagalan bergerak naik, sehingga tag kosong akan terbawa ke setiap bingkai tersebut.
Sumber adalah penunjuk terstruktur — biasanya <file>:<line>:<column> bila posisi YAML tersedia, atau pengenal logis (nama entitas katalog, nama Release, jalur batas) bila tidak ada posisi berkas yang berlaku. Bentuk ketiga, <file> at <key>, muncul bila penunjuk mengetahui dokumen dan kunci penulisan di dalamnya tetapi tidak mengetahui posisi byte: berkas adalah yang Anda buka, dan kunci adalah yang perlu diperiksa setelah berkas terbuka. Pesan adalah diagnostik per permukaan.
Kegagalan tentang satu instance build Anda — sebuah komponen, komponen yang dikontribusikan modul, atau modul itu sendiri — menyebut instance tersebut setelah posisinya, sebagai (instance <name>), sehingga aggregate.yaml (instance shop) adalah Aggregate yang mendeklarasikan modul shop. Jika kegagalan tidak memiliki dokumen untuk ditunjuk, instance berdiri sendiri sebagai instance <name>: penyedia yang gagal saat merender komponen adminer mencetak [TRANSLATION_ERROR E0082] instance adminer, dan baris-baris di bawahnya memuat sisa kegagalan, termasuk dokumen apa pun yang disebutkannya. Namanya adalah nama yang digunakan Aggregate untuk mendeklarasikan komponen tersebut; komponen yang dikontribusikan modul dinamai berdasarkan path-nya melalui modul, seperti shop.cart. Instance tidak pernah dicetak di tempat yang seharusnya berisi file, sehingga apa pun yang mengawali sumber selalu merupakan dokumen yang dapat Anda buka, atau salah satu pengidentifikasi logis di atas.
Aturan yang dievaluasi atas graf yang telah selesai melapor dalam bentuk ketiga tersebut, dan kuncilah yang membedakan dua temuan ketika pesannya saja tidak cukup. Aturan semacam ini menamai tipe komponen yang mendeklarasikan, bukan instansnya, sehingga dua komponen dari satu tipe yang gagal pada aturan yang sama memuat pesan yang sama tentang berkas yang sama:
[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")Kunci adalah satu-satunya bagian yang berbeda, dan kuncilah yang menunjukkan komponen mana dari keduanya yang perlu diedit. Kedua temuan memuat kode pendek yang sama karena keduanya adalah kondisi yang sama, yang terjadi dua kali — kode pendek menamai aturannya, dan kunci menamai kemunculannya.
Dua baris tambahan termasuk dalam bentuk ini, untuk kegagalan yang membawa konteks untuk mengisinya — ekspresi templat yang gagal, dan cuplikan pilar yang berada dalam cakupan di tempat kegagalan terjadi:
[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>Baris expression: memuat kutipan templat yang memicu kegagalan. Blok active pillars: mencantumkan kunci pilar tingkat atas yang tersedia pada titik kegagalan, sehingga penulis dapat melihat apa saja yang dapat dikueri. Keduanya dihilangkan bila kegagalan tidak membawa keduanya.
Bingkai konteks bersarang
Sebuah galat sering melintasi lebih dari satu permukaan dalam perjalanannya menuju CLI: fase pemuatan membungkus kegagalan entitas tertentu, yang pada gilirannya membungkus sebuah sentinel yang menjelaskan aturannya. Setiap bingkai berkategori dalam rantai semacam itu dirender — yang terluar sebagai kepala dalam bentuk di atas, dan setiap bingkai bersarang sebagai lanjutan caused by: yang menjorok, membawa tag kategori, penunjuk sumber, dan pesannya sendiri. Bingkai terdalam yang menunjuk ke berkas selalu terlihat:
[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")Hanya kepala yang membawa kode pendek, dan lanjutan hanya membawa kategorinya. Kondisi disebut satu kali, pada titik pembaca menjumpai kegagalan; bingkai di bawah penanda caused by: adalah kegagalan yang sama dilihat dari lebih dalam, sehingga mengulang pengenalnya pada setiap bingkai hanya menambah baris tanpa menambah fakta. Blok note: bukan lanjutan dan tidak mengikuti aturan ini — blok itu melaporkan kondisi dokumen lain, bukan kondisi yang sama dari lebih dalam; bagian di bawah membahasnya. Kode yang dicetak kepala adalah kode yang disebut oleh rantai — di sini aturan di bagian paling bawah — sehingga bingkai konteks fase di bagian atas tetap mengidentifikasi kondisi di bawahnya.
Dibaca dari atas ke bawah: fase yang gagal, lalu entitas (beserta path berkasnya) yang menyebabkannya, lalu aturan yang dilanggarnya. Bingkai bersarang yang tidak menambahkan apa pun di luar induknya (kategori sama, sumber sama, pesan yang sudah dimuat induknya) dideduplikasi alih-alih diulang, dan penjelasan terminal hanya dirender jika bingkai di atasnya belum memuat teksnya.
Sebuah rantai menjadi lebih dalam setiap kali kegagalan melintasi lebih banyak permukaan dalam perjalanannya keluar, dan aturan ini berlaku di setiap kedalaman. Templat yang ditolak di dalam Workload hasil sintesis sebuah Recipe melintasi tiga — node yang sedang dirender, permukaan templat Recipe, dan templat itu sendiri:
[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)Bacalah dari atas ke bawah seperti sebelumnya, dan perhatikan tiga hal yang diperlihatkan oleh kedalaman tambahan ini. Kode pendek muncul satu kali, pada kepala, berapa pun banyaknya lanjutan yang mengikutinya. Bingkai terdalam adalah tempat kalimat kondisi itu sendiri berada, sehingga baris terdalam adalah baris yang dicocokkan sekaligus baris yang menyebutkan apa yang harus diubah. Dan bingkai tanpa penunjuk sumber hanya mencetak kategorinya: bingkai tengah di atas menyebutkan permukaan tempatnya gagal di dalam pesannya, karena permukaan itu adalah templat, bukan berkas, dan tidak memiliki posisi untuk ditunjuk.
Ketika kegagalan bercabang di bawah sebuah bingkai — fase yang mengumpulkan beberapa pelanggaran independen sebelum berhenti — lanjutan membawa sebuah hitungan, dan setiap kegagalan yang terkumpul dirender di bawahnya, dipisahkan oleh garis --- yang sama dengan yang digunakan rantai multi-galat di bawah:
[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 itKegagalan yang terkumpul di bawah hitungan juga merupakan lanjutan, sehingga tidak satu pun mengulang kode pendek kepala — itulah yang mencegah cabang berisi selusin pelanggaran mencetak pengenal yang sama selusin kali.
Satu tata bahasa pemisah berlaku di seluruhnya: --- di antara kegagalan sejajar, caused by: di antara bingkai konteks bersarang.
Berkas katalog yang ditolak dan kegagalan yang dijelaskannya
Pemuatan katalog untuk menentukan apa yang menjadi dependensi sebuah Release sengaja dibuat toleran: berkas yang tidak dapat dibaca, atau dokumen Aggrega yang tidak dapat di-parse atau diindeks, akan ditolak dan dicatat alih-alih menggagalkan seluruh pemuatan. Itulah yang mencegah entitas rusak yang tidak pernah disentuh Release Anda menggagalkan build yang tidak berkaitan.
Akibatnya, berkas yang ditolak hilang dari katalog tanpa pemberitahuan — dan jika Release Anda memang menjangkaunya, yang gagal adalah upaya menyelesaikan referensi ke apa yang dideklarasikan berkas tersebut. Kegagalan itu merupakan akibat dari penolakan, bukan penolakan itu sendiri, sehingga laporan menyusun keduanya dalam urutan sebab-akibat di mana pun laporan dapat menyebut penolakan tersebut secara tepat:
[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"Penolakan ditampilkan lebih dulu, dengan kategori dan kode singkatnya sendiri, karena penolakan itulah yang menyebut hal yang dapat Anda tindak lanjuti: perbaikannya adalah implements: yang hilang dalam sebuah Recipe, bukan apa pun terkait cara referensi dicari dalam registri. Kegagalan resolusi tetap dilaporkan, di bawahnya, karena kegagalan itulah yang menjelaskan mengapa dokumen tersebut dibutuhkan sama sekali.
Penolakan ditampilkan lebih dulu hanya jika tepat satu berkas yang ditolak mendeklarasikan identitas yang disebut oleh referensi yang gagal. Pencocokan dilakukan pada identitas yang dideklarasikan setiap dokumen untuk dirinya sendiri — jenisnya, namanya, versinya, dan untuk recipe, spec.capability yang menjadi cakupannya — sehingga berkas yang ditolak yang mendeklarasikan apa yang diminta referensi adalah berkas yang akan menjadi hasil resolusi referensi tersebut. Ada dua konsekuensi. Referensi yang menyatakan rentang versi alih-alih satu versi tidak menyebut satu dokumen pun, sehingga tidak menunjuk apa pun. Dan dokumen yang terlalu cacat hingga header-nya tidak dapat dibaca tidak mendeklarasikan identitas apa pun, sehingga tidak pernah disebut sebagai penyebab apa pun.
Jika tidak ada berkas yang ditolak yang mendeklarasikan identitas tersebut, atau lebih dari satu yang mendeklarasikannya, laporannya sama seperti jika tidak ada catatan penolakan: kegagalan ditampilkan lebih dulu, dan setiap penolakan dicantumkan di bawahnya untuk Anda pertimbangkan. Menyebut berkas yang salah sebagai penyebab lebih buruk daripada tidak menyebut apa pun, karena Anda akan bertindak berdasarkan hal itu.
[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 schemaBeberapa hal tentang bentuk kedua itu perlu diketahui, karena masing-masing menjawab pertanyaan yang jika tidak akan muncul dari blok tersebut.
Bagian kepala menyebut kegagalan, bukan penolakan. Kode singkat di bagian atas adalah kode yang dimunculkan oleh kegagalan resolusi, karena kegagalan itulah yang ditampilkan lebih dulu di sini — tidak ada berkas yang ditolak yang ditunjuk, sehingga tidak satu pun darinya mengawali baris tersebut. Kode itu tidak disertai kategori karena tidak ada apa pun di jalur ini yang menggolongkan kegagalan tersebut ke dalam suatu bidang. Kepala masing-masing penolakan berada pada entrinya sendiri di bawah, dan di sanalah Anda membacanya.
Setiap penolakan dicantumkan, bukan hanya yang berpengaruh. Munculnya bentuk ini berarti catatan tersebut tidak dapat menunjuk satu penolakan, sehingga catatan menyatakan pembedanya alih-alih menebak: penolakan di luar closure Release ini ditoleransi dan tidak mungkin menjadi penyebab kegagalan, sehingga penolakan yang menyebut sesuatu yang dijangkau Release menjadi satu-satunya entri yang menjelaskannya. Bacalah entri-entri tersebut dengan membandingkannya terhadap apa yang benar-benar digunakan Release Anda.
Setiap entri membawa kepala dalam kurung siku miliknya sendiri — kategori dan kode singkatnya sendiri. Inilah satu-satunya tempat kode singkat muncul di bawah kepala diagnostik, dan ini bukan pengecualian terhadap aturan kelanjutan di atas melainkan konsekuensinya: entri di bawah note: bukan kegagalan yang sama yang dilihat dari lebih dalam, melainkan kondisi berbeda yang dimunculkan oleh dokumen yang berbeda. Penyebutan kondisinya itulah yang memungkinkan Anda mencari penolakan tersebut dan memperbaiki berkasnya, yang merupakan tindakan yang hendak dimungkinkan oleh blok ini.
Berkas yang ditolak yang header-nya terlalu rusak untuk memulihkan identitas yang dideklarasikannya dicantumkan hanya berdasarkan path-nya. Itulah pembacaan yang jujur atas dokumen yang tidak dapat diintip oleh apa pun, dan path tersebut tetap cukup untuk membuka berkasnya. Berkas yang terlalu rusak bahkan untuk dibaca jenisnya — misalnya berkas yang tidak dapat di-parse sebagai YAML — dicantumkan dengan cara ini jika berkas itu mendeklarasikan apiVersion Aggrega, melalui baris yang diawali, tanpa indentasi, dengan apiVersion: dan nilai yang diawali aggrega.ai/, disertai alasan dari parser itu sendiri: baris tersebut, dan apa yang diharapkan parser di sana. Berkas YAML yang mendeklarasikan apiVersion lain, atau tidak mendeklarasikannya sama sekali, bukanlah dokumen Aggrega — misalnya template chart, atau berkas konfigurasi yang disimpan di samping entitas — sehingga berkas itu tidak pernah dicantumkan, seberapa pun rusaknya.
File yang mendeklarasikan jenis yang tidak ada di katalog mana pun hanya disebutkan jika file itu menjelaskan kegagalannya. Dokumen yang mendeklarasikan apiVersion Aggrega dan kind yang tidak ada di katalog mana pun — misalnya Componnent yang salah eja — dilewati oleh setiap pemuatan, sehingga dokumen itu bukan penolakan dan tidak dicantumkan di antara penolakan. Jika referensi yang gagal meminta nama yang dideklarasikan file tersebut, dan versinya bila referensi menyebutkan versi, laporan menyebut file itu dalam catatan tersendiri di bawah kegagalan, apa pun jenis yang digunakan saat referensi itu dikumpulkan — di setiap antarmuka yang tercantum di bawah, dan di aggrega build baik saat membaca lockfile yang sudah ada maupun saat mengisinya terlebih dahulu:
[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 directoriesKegagalan tetap ditampilkan pertama: jenis yang dideklarasikan file tidak menyebut identitas apa pun, sehingga file itu tidak pernah dipilih sebagai penolakan yang membuka laporan. Penjelasan tentang dari mana entitas lokal dibaca tidak disertakan dalam laporan itu, karena file sudah berada di tempat katalog membaca dan memindahkannya tidak akan membantu. File dengan jenis yang tidak ada di katalog mana pun yang mendeklarasikan nama lain tidak menjelaskan apa pun tentang kegagalan ini dan tidak disebutkan. aggrega serve, yang pesannya hanya satu baris, membawa catatan yang sama di baris itu — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: diikuti penolakan file tersebut — dan tidak pernah mencantumkan file seperti itu di antara file yang dilewati saat pemuatan; tool describe dari aggrega mcp, saat diminta sebuah nama menurut ketentuan sebuah Release, juga menyebut file itu sebagai pengganti penjelasan tersebut. aggrega validate dan aggrega lint untuk seluruh katalog melaporkan setiap file seperti itu, baik ada maupun tidak ada yang menjangkaunya — lihat fatal-halts.md §“A catalog document declares a kind a catalog does not hold (Dokumen katalog mendeklarasikan jenis yang tidak ada di katalog)”.
Bentuk mana pun yang Anda dapatkan, kegagalan tetap mempertahankan identitasnya sendiri. Catatan ditambahkan pada kegagalan, bukan ditampilkan menimpanya, dan menampilkan penolakan lebih dulu hanya mengubah apa yang Anda baca pertama kali — sehingga kondisi yang dimunculkan kegagalan tetap utuh dalam kedua bentuk: kode singkatnya tetap dapat ditelusuri, dan alat yang mencocokkan kondisi tersebut tetap cocok.
Jika dokumen yang ditolak itu sendiri yang dilaporkan oleh suatu perintah, penolakan dinyatakan satu kali. aggrega inspect <name> memuat katalog secara ketat, sehingga dokumen yang ditolak oleh pemuatan akan menghentikannya, dan yang dicetaknya adalah penolakan dokumen tersebut sebagai satu diagnostik: kepala yang membawa kategori dan kode singkat penolakan, dokumen tersebut sebagai sumbernya, dan di bawahnya apa yang salah pada dokumen — untuk pelanggaran skema, kunci yang dilanggar beserta baris dan kolomnya, serta sarannya. Pemuatan yang memunculkannya melewati direktori yang sedang ditelusurinya dan langkah yang membaca berkas, dan keduanya tidak dicetak sebagai frame tersendiri, karena masing-masing akan menyebut dokumen yang sama lagi tanpa menambahkan fakta. aggrega serve, ketika ditanya apa yang dirujuk oleh suatu nama di mana dokumen yang ditolak mendeklarasikan nama itu, menjawab dengan penolakan yang sama dalam kata-kata yang sama pada satu baris, diikuti catatan bahwa berkas tersebut dilewati saat pemuatan. Seperti di atas, kondisi penolakan tetap dapat dicocokkan dalam kedua cara.
Kedua bentuk sampai kepada Anda di mana pun resolusi tersebut dijalankan. aggrega build, aggrega pull, aggrega validate --release, dan aggrega inspect --closure menghasilkannya di terminal, begitu pula aggrega validate atas satu Recipe yang target implements-nya tidak ditemukan, dan asisten AI yang terhubung melalui aggrega mcp menerima penjelasan yang sama dari alat build dan validate, serta penolakan yang ditampilkan lebih dulu dalam satu baris dari pembacaan catalog:// atas entitas yang dideklarasikan file yang ditolak. Permukaan tempat Anda bertanya tidak mengubah apa pun tentang berkas mana yang harus Anda buka — pemanggil yang mengakses aggrega mcp melalui HTTP diberi tahu berkas itu secara relatif terhadap root workspace, dan tidak diberi tahu berkas di luar workspace yang dilayani server tersebut — dan jika penolakan ditampilkan lebih dulu, kontrak penulisan yang dirujuk jawaban adalah kontrak untuk jenis yang dideklarasikan dokumen yang ditolak tersebut — bukan jenis referensi yang gagal.
Kelas kegagalan amplop dokumen
Setiap dokumen entitas — entitas katalog, Aggregates, Manifests, Releases — divalidasi terhadap JSON Schema yang dipublikasikan untuk jenisnya saat dimuat, sebelum parsing bertipe. Dokumen yang melanggar amplopnya (kunci yang tidak dikenal, bidang wajib yang hilang, nilai dengan bentuk yang salah, konstruksi terlarang seperti Release values:) dihentikan secara tegas dengan diagnostik yang pertama-tama menyebutkan kondisinya, lalu jenis entitas dan berkasnya, lalu setiap kunci atau bentuk yang bermasalah beserta baris dan kolom tempatnya berada, dan terakhir apa yang perlu dilakukan:
[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 schemaDiagnostik dibuka dengan kondisi, menyebutkan jenis dan berkas, lalu ditutup dengan apa yang perlu dilakukan; setiap pelanggaran di antaranya hanya membawa line:column, karena bagian kepala sudah menyebutkan berkasnya. Setiap kunci yang bermasalah dilaporkan pada posisi miliknya sendiri, bukan pada posisi blok yang memuatnya, sehingga baris dan kolom menunjuk ke kunci yang perlu Anda ubah. Jika bentuk pada posisi tersebut berasal dari definisi yang dapat digunakan ulang di dalam skema, diagnostik menyebutkan definisi itu setelah kata against — against /$defs/boundary di atas — sehingga jelas kontrak mana yang menjadi acuan pengukuran kunci tersebut, dan definisi itu tidak terbaca sebagai satu langkah lagi di sepanjang jalur kunci yang Anda tulis. Dokumen dengan beberapa pelanggaran mencantumkan masing-masing pada posisinya sendiri, dalam urutan kunci, dan laporan berhenti setelah empat pelanggaran dengan jumlah sisanya.
Ada dua hal yang perlu diketahui tentang ke mana sebuah posisi menunjuk, karena keduanya berguna alih-alih mengejutkan:
- Kunci wajib yang hilang tidak memiliki posisi sendiri — menurut definisinya, kunci itu tidak ada di dalam dokumen. Sebagai gantinya, pelanggaran menunjuk ke kunci yang melingkupinya, yaitu tempat entri yang hilang itu seharusnya berada. Jadi
spec.capability: missing required propertymenunjuk kespec:, dan di situlah Anda menambahkannya. - Kunci yang namanya sendiri mengandung titik — setiap label
component.aggrega.ai/…dan anotasifeatures.aggrega.ai/…— dilaporkan pada blok yang memuatnya, bukan pada entri itu sendiri, karena titik-titik tersebut terbaca sebagai langkah turun ke dalam dokumen. Pelanggaran pada sebuah label menunjuk kelabels:.
Jika sebuah pelanggaran menyebutkan kunci yang sama sekali tidak ada di dalam dokumen — misalnya seluruh blok metadata: dihilangkan — posisinya dihilangkan alih-alih ditebak, dan pelanggaran hanya terbaca sebagai jalur kunci dan pesannya. Posisi yang harus Anda ragukan lebih buruk daripada tidak ada posisi sama sekali.
Kategorinya mengikuti permukaan penulisan: [CATALOG_ERROR] untuk entitas katalog, [DEVELOPER_ERROR] untuk Aggregates, [OPS_ERROR] untuk Releases dan Manifests. Gerbang yang sama berjalan di setiap permukaan yang memuat entitas — aggrega build, aggrega lint, aggrega validate, dan diagnostik editor yang dipublikasikan aggrega serve — sehingga kunci yang nyasar atau salah eja ditolak di mana pun dokumen pertama kali dibaca, alih-alih dibuang diam-diam. Setiap permukaan tersebut menentukan posisi dengan cara yang sama, sehingga semuanya menunjuk ke kunci yang sama, dan masing-masing membaca kalimat kondisi dari kondisi itu sendiri: baris yang digarisbawahi editor Anda adalah baris yang disebutkan terminal, dan kalimat pembuka entri editor adalah kalimat pembuka terminal. Yang tidak sama di antara kedua permukaan adalah keseluruhan pesannya, dan hal itu disengaja — terminal mengelompokkan setiap temuan di bawah satu header dan menutup dengan saran untuk jalurnya, sedangkan editor mengeluarkan satu entri per temuan, diposisikan pada kuncinya sendiri, tanpa mengulang berkas tempat entri itu sudah terlampir maupun saran yang seharusnya cukup disampaikan sekali, bukan pada setiap garis bawah. Jadi, bagian yang sama adalah bagian yang membuat Anda mengenali kondisinya.
Rantai multi-galat
Ketika satu kompilasi mendeteksi beberapa pelanggaran yang saling independen (paling umum selama analisis statis, ketika setiap pelanggaran selector dan appliesTo dikumpulkan sebelum salah satunya menghentikan build), galat-galat tersebut digabungkan menjadi satu rantai. CLI menelusuri rantai tersebut dan menampilkan setiap sub-galat secara terpisah, dipisahkan oleh baris garis 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.Pemisah --- bersifat literal — pembaca dan alat hilir dapat memisahkan keluaran berdasarkan pemisah ini untuk menghitung galat-galat yang digabungkan. Setiap sub-galat merupakan kegagalan tersendiri, bukan rincian dari galat di sebelahnya, sehingga masing-masing membawa kepalanya sendiri: kategorinya sendiri dan kode singkatnya sendiri, masing-masing jika ada, sebagaimana dijelaskan bagian tentang token yang tidak ada. Dua pelanggaran terhadap satu aturan menyebutkan kode singkat yang sama, seperti di atas; dua pelanggaran terhadap aturan yang berbeda menyebutkan kode yang berbeda.
Membaca error dari awal hingga akhir
Dalam sebagian besar konteks penulisan, prefiks kategori dan penunjuk sumber bersama-sama mengidentifikasi apa yang perlu diperbaiki:
| Kategori | Letak perbaikan | Contoh permukaan |
|---|---|---|
[DEVELOPER_ERROR] | YAML Aggregate | Pelanggaran selector / appliesTo pada apa yang ditulis oleh Aggregate; ketidakcocokan socket uses di sisi Aggregate; penghentian resolver pada penulisan oleh developer. |
[OPS_ERROR] | YAML Release / YAML Manifest | Templat path boundary mereferensikan field yang tidak didukung; subDirectory menyebabkan tabrakan path; penghentian resolver pada penulisan Release; koneksi yang dihubungkan oleh Release, atau attachment yang diisinya pada suatu koneksi, ditolak oleh aturan socket atau slot; Feature yang hanya dilampirkan oleh Release, ke suatu komponen atau ke suatu boundary, ditolak oleh aturan Feature atau slot; pemetaan atau binding anotasi Manifest ditolak. |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Aturan bentuk Recipe; templat FeatureRecipe mereferensikan field yang khusus per komponen dengan executionScope: boundary; pemeriksaan silang featuresSchema Workload gagal. |
[TRANSLATION_ERROR] | Workload / output valuesMapping / overlay sumber | Resolusi port probe Helm; tabrakan nama layanan compose antar-boundary; dua kontributor compose yang mendeklarasikan satu nama volume atau config tingkat atas dengan isi yang bertentangan; ketidakcocokan nama chart pada umbrella helm-chart. |
[FETCH_ERROR] | Akuisisi registry / sumber jarak jauh (operasional, bukan penulisan) | Artefak tidak ditemukan di registry; autentikasi diperlukan; jaringan tidak dapat dijangkau; digest yang di-cache tidak cocok dengan lockfile. Perbaikan: lakukan autentikasi, pulihkan konektivitas, atau aggrega pull --upgrade --release <release>. |
[POLICY_ERROR] | Plugin kebijakan (aturan tata kelola) | Plugin kebijakan yang dilampirkan pada peran putusan tata kelola menolak build yang telah dirakit berdasarkan aturan yang ditegakkannya. Perbaikan: penuhi kebijakan yang ditegakkan atau pertimbangkan kembali attachment tersebut. |
[TRUST_ERROR] | Konfigurasi kepercayaan, atau tanda tangan artefak itu sendiri (suatu persoalan, bukan permukaan penulisan) | Kebijakan kepercayaan atau root kepercayaan yang dipatok yang tidak dapat dibaca; kebijakan keyless yang tidak mendeklarasikan identitas tepercaya; kebijakan penandatanganan yang mewajibkan tanda tangan untuk jenis yang sedang dipublikasikan; gerbang attachment putusan yang tercatat yang tidak lagi dilampirkan oleh konfigurasi. Atau: tanda tangan yang tidak terverifikasi; artefak tanpa tanda tangan padahal diwajibkan; penanda tangan yang tidak tepercaya; plugin yang identitas tepercayanya yang tercatat tidak lagi cocok. Perbaikan: koreksi konfigurasi atau catatan kepercayaan yang di-commit, atau ambil keputusan tentang artefak tersebut — kode singkat menunjukkan yang mana. |
Prefiks konteks per provider (helm: node "<id>": ..., compose: node "<id>": ...) muncul di dalam bagian pesan dari output [TRANSLATION_ERROR] dan [CATALOG_ERROR] untuk melokalkan provider yang gagal ketika lebih dari satu provider terlibat.
Galat bawaan pustaka
Galat yang berasal dari dalam pustaka yang mendasarinya (galat pemuatan chart dari Helm SDK, galat parser YAML docker-compose, galat I/O berkas akibat jalur sumber yang tidak ada) dibungkus dengan awalan konteks per provider dan muncul di bawah [TRANSLATION_ERROR] atau [CATALOG_ERROR], bergantung pada apakah galat tersebut terjadi saat sintesis atau saat pemuatan konten katalog. Pesan pustaka yang dibungkus mempertahankan diagnostik alat aslinya kata demi kata sehingga penulis dapat mencocokkannya dengan dokumentasi alat itu sendiri.
Rujukan silang
fatal-halts.md— katalog per galat untuk setiap penghentian fatal, beserta pesan yang dimaksudkan dan cara memperbaikinya.warnings.md— peringatan non-fatal yang dikeluarkan oleh kompiler.vocabulary/validation-surface.md— empat lapisan validasi skema dan bagaimana bentuk galatnya saling berinteraksi.