Hata çevirisi disiplini
Aggrega’nın derleme hattı hataları birçok yüzeyden üretir: şema doğrulayıcıları, çözümleyici, IR oluşturucu, sağlayıcılar, Go şablon motoru ve sağlayıcıların sarmaladığı alttaki YAML / Helm / docker-compose kütüphaneleri. CLI’ya kadar yükselen hatalar, en fazla iki şeyi adlandıran köşeli parantezli bir başlıkla açılır: hangi konuya bakılacağını söyleyen bir kategori (çoğu değer için hatalı olan yazım yüzeyi) ve derlemeyi durduran koşulun kısa kodu. Bunları bir kaynak işaretçisi ve bir ileti izler. Koşulu bir eklenti oluşturduysa kod, onu oluşturan eklentiyle nitelenir; çünkü aynı koşulu birden fazla eklenti bildirebilir. Bu sayfa, yazarların hata iletilerini doğrudan yorumlayabilmesi için bu çıktının biçimini belgeler.
Hata başına katalog (her ölümcül durdurma ve nasıl düzeltileceğine ilişkin yönergeler) için fatal-halts.md sayfasına bakın. Dört şema doğrulama katmanı ve bunların hata biçimlerinin birbiriyle nasıl etkileştiği için vocabulary/validation-surface.md sayfasına bakın.
Hata kategorileri
Kategori etiketi, hangi konuya bakılacağını söyler. Çoğu, düzeltmenin yapılacağı yazım yüzeyini adlandırır; geri kalanlar kimsenin yazım hatası olmayan bir konuyu adlandırır — bir yapıtın edinilmesi, bir yönetişim kararı ya da güven ve imzalama — ve her durumda belirli koşulu tanımlayan, başlıkta kategorinin yanındaki kısa koddur:
[DEVELOPER_ERROR]— hata, Aggregate yazımına bağlıdır. Düzeltme, Aggregate YAML’ında ya da kataloğun geliştirici tarafından yazılan kısmındadır (Component değerleri,usessoketleri, Feature ekleri). Örnek yüzeyler: Aggregate tarafındaki sorunlarda çözümleyici durmaları; Aggregate’in yazdıkları üzerindeki seçici veappliesToihlalleri.[OPS_ERROR]— hata, operatörün kendi belgelerine, yani Release’e ve Manifest’e bağlıdır. Düzeltme, Release YAML’ında (sınır topolojisi, parametre değerleri, Release düzeyindeki Feature ekleri) ya da Manifest YAML’ındadır (bir türün hangi Recipe üzerinden dağıtıldığı ve yanına yazılan açıklama bağlamaları). Örnek yüzeyler: Release şema doğrulaması; sınır yolu şablonu değerlendirmesi; sağlayıcılar arasındasubDirectoryçakışmaları; Manifest eşleme ve açıklama bağlama retleri; Release’in kurduğu bir bağlantıyı ya da bir bağlantıda doldurduğu bir eki reddeden bir kural — bir soketin seçicisi, bir yuvanın seçicisi, bir soketin zorunlu olarak bildirdiği bir yuva; yalnızca Release’in bir bileşene ya da bir sınıra eklediği bir Feature’ı reddeden bir kural — Feature’ınappliesToalanı, bir yuvanın seçicisi, bildirilen şeması.[CATALOG_ERROR]— hata, bir katalog varlığına (Recipe, FeatureRecipe, Component, Feature, Plugin) bağlıdır. Düzeltme katalog içeriğindedir. Örnek yüzeyler: Recipe biçim kuralları; WorkloadfeaturesSchemaçapraz denetimleri; katalogda yazılmış şablonlardaki şablon ayrıştırma hataları.[TRANSLATION_ERROR]— hata, sağlayıcı tarafındaki sentezlemeye bağlıdır (bir sağlayıcı eklentisinin bir Workload’u, valuesMapping çıktısını ya da kaynaklı bir katmanı sağlayıcıya özgü yapıtlara çevirmeye çalışması). Düzeltme genellikle Workload’ınservices/containers/volumesbiçiminde, Recipe’ninvaluesMappingşablon çıktısında ya da kaynak kipi katman yapısındadır.[FETCH_ERROR]— hata, sabitlenmiş bir bağımlılığın bir kayıt defterinden ya da uzak bir kaynaktan getirilmesine bağlıdır; herhangi bir yazım yüzeyine bağlı değildir. Düzeltme genellikle işletimseldir: kayıt defterinde kimlik doğrulayın (docker login <registry>), bağlantıyı yeniden sağlayın ya da kaymış veya kurcalanmış bir yapıtı yeniden sabitleyin (aggrega pull --upgrade --release <release>). Örnek yüzeyler: kayıt defterinde bulunamayan bir katalog varlığı ya da chart; gerekli olan ya da başarısız olan kimlik doğrulama; erişilemeyen ağ; önbellekteki bir yapıtın özetinin kilit dosyasıyla eşleşmemesi. Getirme hataları, iletide somut bir çözüm işaretçisi taşır.[POLICY_ERROR]— derleme, bir yönetişim kararı rolüne eklenmiş bir ilke eklentisi tarafından reddedilmiştir. Bu bir yazım yüzeyi hatası değildir: girdi doğru biçimlidir, ancak eklentinin uyguladığı bir yönetişim kuralını (uyumluluk, FinOps ya da güvenlik) karşılamaz. Düzeltme, yazdıklarınızı uygulanan ilkeyle uyumlu hâle getirmek ya da ilke ekini yeniden değerlendirmektir. İleti, reddeden eklentiyi adlandırır ve eklentinin sağladığı kural iletisini taşır.[TRUST_ERROR]— güven ve imzalama katmanı işlemi reddetmiştir. Bu kategori bir yazım yüzeyini değil bir konuyu adlandırır ve yanındaki kısa koddan ayırt edebileceğiniz iki çözümü kapsar. Güven yapılandırmanız yanlıştır: okunamayan bir güven ilkesi, yüklenemeyen sabitlenmiş bir güven kökü, hiçbir güvenilir kimlik bildirmeyen anahtarsız bir ilke, yayımladığınız yapıt türü için imza gerektiren bir imzalama ilkesi ya da yapılandırmanızın artık eklemediği bir karar eki için güvenilir olarak kaydedilmiş bir eklenti. Bu yapıt doğrulamada başarısız oldu: güven çapasına karşı doğrulanmayan bir imza, imzanın gerektiği yerde imza taşımayan bir yapıt, gerçek ama güvenilmeyen bir imzalayıcıdan gelen bir imza ya da kaydedilmiş güvenilir kimliği artık çözümlenen şeyle eşleşmeyen bir eklenti. İlk durumda düzeltme yapılandırmanızda ya da işlenmiş güven kaydındadır; ikincisinde ise yapıt hakkında bir karardır — incelenmiş olanı geri yükleyin ya da değişeni inceleyip yeniden kaydedin.
Bir Feature eki hakkındaki bulgu, onu yazan belgeyi izler
Bir Feature her iki belgede de eklenebilir — Aggregate onu bir bileşene ya da bir alt sisteme, Release ise bir bileşene ait girdisine ya da bir sınıra ekler — bu nedenle bir ek hakkındaki bulgunun kategorisi, ekin ulaştığı bileşenden değil, ekin yazıldığı yerden okunur. Bulgu, o belgede eki yazan features: girdisinde konumlandırılır ve o belgenin yazarı altında kaydedilir: yalnızca Release’in yaptığı bir ek, Release’in kendi yolunda [OPS_ERROR] olarak, Aggregate’in yaptığı ise Aggregate’in yolunda [DEVELOPER_ERROR] olarak bildirilir.
[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.Her iki belge tek bir eki birlikte yazdığında — Aggregate Feature’ını adlandırır, Release onu boyutlandırır — ekin bütünü hakkındaki bulgu, Feature’ının adlandırıldığı yerde, yani Aggregate’te konumlandırılır. Yapılandırmasının bir parçası hakkındaki bulgu, o parçanın yazıldığı yerde konumlandırılır: values geliştiricinindir ve Aggregate’tedir, infra ise operatöründür ve Release’tedir. Açıklama güdümlü genişletmenin ürettiği bir ek hiçbir features: girdisi tarafından yazılmamıştır; bu nedenle onunla ilgili bulgu, bileşeni bildiren belgede bileşende [DEVELOPER_ERROR] olarak konumlandırılır.
Boş bırakılan zorunlu bir yuva, hiçbir belgenin yazmadığı tek durumdur. İşaret edilecek bir ek yoktur; bu nedenle bulgu Aggregate’teki bileşende kalır ve [DEVELOPER_ERROR] olarak kaydedilir; çözümü ise her iki belgeyi de adlandırır, çünkü yuvayı ikisinden biri doldurabilir: “Bu ada, Aggregate’te ya da Release’te, bileşende ya da onun üstündeki bir kapsamda bir Feature ekleyin.”
Düzenleyici de aynı yerleşimi okur: Release’te konumlandırılmış bir bulgu, Release’in belgesinde, onu yazan anahtarda gösterilir; Aggregate’in belgesinde ise hiç gösterilmez; Aggregate’in içe aktardığı bir modülün belgesinde konumlandırılmış bir bulgu da aynı şekilde o modülün belgesinde gösterilir.
Çıktı biçimi
Yazdırılan bir tanılama, köşeli parantezli başlık ve kaynak işaretçisiyle başlar ve iletiyi girintili ayrı bir satıra koyar:
[CATEGORY SHORTCODE] <source> <message>Başlık iki belirteç taşır ve bunlar farklı soruları yanıtlar. Kategori, yukarıdakilerden biridir ve hangi konuya bakılacağını söyler. Kısa kod, E harfi ve dört rakamdır; derlemeyi durduran koşulu tam olarak adlandırır: bunu bir raporda alıntılayın, bir aramaya yazın ya da sentinels.md içindeki tüm koşulların tablosunda karşılığını bulun. Biri diğerinden türetilemez, bu yüzden ikisi de yazdırılır; bir kategori birden fazla çözümü kapsadığında, [TRUST_ERROR] örneğinde olduğu gibi, hangisiyle karşılaştığınızı size kısa kod söyler.
Bir eklentinin oluşturduğu kod, onu oluşturan eklentiyle nitelenir
Her kısa kod, Aggrega’nın bildirdiği bir koşulu adlandırır ve hiçbir iki koşul aynı kodu paylaşmaz: başka bir koşulun zaten sahip olduğu bir numarayla bildirilen bir koşul, derleyici herhangi bir girdiyi okumadan önce reddedilir. Bir eklenti kendine ait kod ayırmaz. Bir hata bildirdiğinde, Aggrega’nın bildirdiği koşullardan birini — bir eklentinin nasıl başarısız olduğunu tanımlayan birkaç genel koşuldan birini ya da uygun düştüğünde daha belirli bir koşulu — adlandırır ve gerçekte ne olduğunu söyleyen cümleyi sağlar. Bu nedenle iki eklenti aynı kısa kodu bildirebilir ve bunu yaptıklarında aynı koşulu bildiriyorlardır.
Kodun söyleyemeyeceği şey, koşulla hangi eklentinin karşılaştığıdır; bu nedenle bir eklentinin oluşturduğu koşulu bildiren başlık, eklentinin kimliğini kodun hemen önünde taşır:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>Kısa kod her zaman son bölümdür: son / işaretinden sonra gelen, E harfi ve dört rakam. Bir eklentinin kimliği kendi ayırıcılarını taşır ve bir sürüm de taşıyabilir; bu yüzden kodu her başlıktan geri elde edilebilir kılan, ilk / işaretinden değil sondan okumaktır. Bu son bölümden önceki her şey eklentidir.
Son segment, onu hangi eklenti oluşturmuş olursa olsun, diğer her kısa kod gibi çözümlenir: sentinels.md içindeki her koşulun tablosu onu listeler ve aggrega explain onu çözümler. Yalnızca son segmenti alıntılayın — niteleyici, koşulla hangi eklentinin karşılaştığını söyler, hangi koşul olduğunu değil. Aggrega’nın bildirmediği bir kodu — hiçbir koşulun sahip olmadığı bir numarayı ya da kullanımdan kaldırılmış birini — adlandıran bir eklentinin bu kodu yazdırılmaz: derleme, o eklentiyle nitelenmiş E0293 ile durur ve iletisi eklentinin sunduğu kodu alıntılar, o genel koşulları adlandırır ve eklentinin kendi cümlesini korur.
Yalın bir kısa kod yazdıran başlık, Aggrega’nın kendisinin oluşturduğu bir koşulu bildirir; buna bir eklentinin başarısız olup kendine ait hiçbir koşul adlandırmadığı durum da dahildir. Bu durumda derlemeyi durduran, derleyicinin genel eklenti hatası koşuludur ve ayrıntıyı eklentinin iletisi taşır.
Belirteçlerden biri eksik olabilir ve eksik olan atlanır
Tanılamanın sahip olmadığı bir belirtecin yerini hiçbir şey tutmaz: yer tutucu da boş köşeli parantez de yoktur. Bir başlığın kısa olabileceği üç durum vardır ve her biri size bir şey söyler:
- Kısa kod yok. Hata, Aggrega’nın kendine ait hiçbir koşulunu adlandırmaz; çoğu zaman derleyicinin sarmaladığı bir kitaplığın bildirdiği bir hatadır. Başlık yalnızca kategoriyi yazdırır, böylece hangi yüzeye bakacağınızı yine de bilirsiniz.
- Kategori yok. Hatanın sizi yönlendireceği bir konu yoktur, bu yüzden tahmin edilmez. Başlık yalnızca kısa kodu yazdırır ve karşılığını bulacağınız şey koddur. Bunu iki durum oluşturur ve sizin açınızdan aynı oldukları için aynı okunurlar: hiçbiri nereye bakacağınızı söylemez ve ne olduğunu kod söyler. Biri derleyicinin kendisindeki bir hatadır; ileti bunu belirtir ve bildirmenizi ister; ortaya çıkan durum, derleyicinin katalogla ilgili kendi görünümlerinin birbiriyle uyuşmamasıdır. Diğeri, bir koşulu adlandıran ancak onu bir konu altına yerleştiren bir yüzeyden hiç geçmemiş bir hatadır; komut sınırında oluşturulan bir ret için olağan biçim budur. Boşluğu doldurmak için asla bir kategori uydurulmaz ve bu, atlamanın bir kısıtı değil amacıdır: kategori “hangi konuya bakmalıyım” sorusunu yanıtlar ve sorunun yanıtı olmadığı yerde verilen bir yanıt temkinli bir yanıt değil, ilk önce uygulanacak yanlış bir yanıttır. Tersi çıkarımın da geçerli olmadığını belirtmek gerekir: kategori taşıyan bir başlık her zaman sizin yazdığınız bir şeye işaret etmez, çünkü
[FETCH_ERROR],[POLICY_ERROR]ve[TRUST_ERROR]her biri bir yazım yüzeyini değil bir konuyu adlandırır. - Hiçbiri yok. Köşeli parantezler tamamen atlanır ve tanılama iletisinin kendisidir. Bu, Aggrega’nın kendine ait hiçbir koşulunu adlandırmayan ve sizi yönlendireceği bir konusu olmayan bir hatadır: argümanlarını reddeden bir komut, okunamayan bir dosya, bir iptal ya da derleyicinin altında bizim hiçbir koşulumuz olmadan sarmaladığı bir kitaplığın bildirdiği bir hata.
sentinels.mdiçinde karşılığı aranacak bir şey yoktur ve hatanın söyleyeceklerinin tamamı iletidir.
Aynı hatanın tek satıra indirgenmiş hâli, yani terminal yerine günlük çıktısına uygun biçim, kategoriyi taşır ve kısa kodu atar:
[CATEGORY] <source>: <message>Başlıkta bulunmayan bir kategori burada da köşeli parantezleriyle birlikte bulunmaz; bu yüzden bu satır asla [] <source>: <message> olmaz. Tek satırlık biçim, hata yukarı doğru ilerledikçe kapsayan çerçevelere yeniden sarılır; dolayısıyla boş bir etiket bu çerçevelerin her birine taşınırdı.
Kaynak, yapılandırılmış bir işaretçidir: bir YAML konumu mevcutsa genellikle <file>:<line>:<column>, hiçbir dosya konumu geçerli değilse mantıksal bir tanımlayıcı (katalog varlığının adı, Release adı, sınır yolu). Üçüncü bir biçim olan <file> at <key>, işaretçi hem belgeyi hem de içindeki yazım anahtarını bildiği ancak bayt konumunu bilmediği durumda görünür: dosya açacağınız şeydir, anahtar ise açtıktan sonra bakacağınız yerdir. İleti, yüzeye özgü tanılamadır.
Derlemenizin bir örneğiyle ilgili bir hata — bir bileşen, bir modülün katkıda bulunduğu bir bileşen ya da bir modülün kendisi — o örneği konumdan sonra (instance <name>) olarak adlandırır; dolayısıyla aggregate.yaml (instance shop), shop modülünü bildiren Aggregate’tir. Hatanın işaret edeceği bir belge olmadığında örnek tek başına instance <name> olarak yer alır: adminer bileşenini işlerken başarısız olan bir sağlayıcı [TRANSLATION_ERROR E0082] instance adminer yazdırır ve altındaki satırlar, adlandırdığı herhangi bir belge dahil, hatanın geri kalanını taşır. Ad, Aggregate’in bileşeni altında bildirdiği addır; bir modülün katkıda bulunduğu bir bileşen, shop.cart gibi modül üzerinden giden yoluyla adlandırılır. Bir örnek asla bir dosyanın yer alması gereken yerde yazdırılmaz; bu nedenle kaynağın başladığı şey her zaman açabileceğiniz bir belge ya da yukarıdaki mantıksal tanımlayıcılardan biridir.
Tamamlanmış grafik üzerinde değerlendirilen bir kural bu üçüncü biçimde bildirir ve ileti tek başına yetmediğinde iki bulguyu birbirinden ayıran anahtardır. Bu türden bir kural, örneği değil bildiren bileşen türünü adlandırır; bu yüzden aynı kuralı ihlal eden aynı türden iki bileşen, aynı dosya hakkında aynı iletiyi taşır:
[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")Farklı olan tek kısım anahtardır ve iki bileşenden hangisinin düzenleneceğini o adlandırır. Her iki bulgu da aynı kısa kodu taşır, çünkü ikisi de iki kez karşılaşılmış aynı koşuldur: kısa kod kuralı, anahtar ise oluşumu adlandırır.
Bunları dolduracak bağlamı taşıyan bir hata için biçime iki satır daha eklenir: başarısız olan şablon ifadesi ve başarısız olduğu noktada kapsamdaki sütunların bir anlık görüntüsü:
[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: satırı, hatayı tetikleyen şablon alıntısını taşır. active pillars: bloğu, hata noktasında kullanılabilen üst düzey sütun anahtarlarını listeler; böylece yazarlar neyin sorgulanabilir olduğunu görür. Hata ikisini de taşımıyorsa ikisi de atlanır.
İç içe bağlam çerçeveleri
Bir hata, CLI’a ulaşana kadar çoğu zaman birden fazla yüzeyden geçer: bir yükleme aşaması belirli varlık hatasını sarar, o da kuralı açıklayan bir sentinel’i sarar. Böyle bir zincirdeki kategorili her çerçeve görüntülenir: en dıştaki, yukarıdaki biçimde baş olarak; iç içe her çerçeve ise kendi kategori etiketini, kaynak işaretçisini ve iletisini taşıyan girintili bir caused by: devamı olarak. Dosyaya işaret eden en içteki çerçeve her zaman görünür:
[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")Kısa kodu yalnızca baş taşır; devamlar yalnızca kategorilerini taşır. Koşul, okuyucunun hatayla karşılaştığı noktada bir kez adlandırılır; bir caused by: işaretinin altındaki çerçeveler aynı hatanın daha içeriden görünüşüdür, bu nedenle tanımlayıcısını her birinde yinelemek olgu eklemeden satır eklerdi. Bir note: bloğu devam değildir ve bu kurala uymaz: aynı koşulu daha içeriden değil, başka belgelerin koşullarını bildirir; aşağıdaki bölüm bunu ele alır. Başın yazdırdığı kod, zincirin adlandırdığı koddur (burada en alttaki kural), bu nedenle en üstteki bir aşama bağlamı çerçevesi yine de altındaki koşulu tanımlar.
Yukarıdan aşağı okunduğunda: başarısız olan aşama, ardından buna neden olan varlık (dosya yoluyla birlikte), ardından ihlal ettiği kural. Üst çerçevesinin ötesinde bir şey eklemeyen iç içe bir çerçeve (aynı kategori, aynı kaynak, üst çerçevenin zaten içerdiği bir ileti) yinelenmek yerine tekilleştirilir; son bir açıklama ise yalnızca üstündeki çerçeveler onun metnini zaten taşımıyorsa görüntülenir.
Bir hata dışarı çıkarken daha fazla yüzeyden geçtiğinde zincir derinleşir ve kural her derinlikte geçerlidir. Bir Recipe’in sentezlenmiş Workload’u içinde reddedilen bir şablon üç yüzeyden geçer: işlenen düğüm, Recipe’in şablon yüzeyi ve şablonun kendisi:
[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)Bunu önceki gibi yukarıdan aşağı okuyun ve ek derinliğin görünür kıldığı üç şeye dikkat edin. Kısa kod, ardından kaç devam gelirse gelsin, yalnızca bir kez, başta görünür. Koşulun kendi cümlesi en içteki çerçevededir, bu nedenle en derin satır hem eşleştirilecek satır hem de neyin değiştirileceğini söyleyen satırdır. Ve kaynak işaretçisi olmayan bir çerçeve yalnızca kategorisini yazdırır: yukarıdaki ortadaki çerçeve, başarısız olduğu yüzeyi iletisi içinde adlandırır, çünkü o yüzey bir dosya değil bir şablondur ve işaret edilecek bir konumu yoktur.
Hata bir çerçevenin altında dallandığında (durmadan önce birkaç bağımsız ihlal toplayan bir aşama), devam bir sayı taşır ve toplanan her hata, aşağıdaki çoklu hata zincirlerinin kullandığı aynı --- ayırıcısıyla ayrılarak onun altında görüntülenir:
[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 itSayının altındaki toplanmış hatalar da devamdır, bu nedenle hiçbiri başın kısa kodunu yinelemez; düzinelerce ihlalden oluşan bir dallanmanın aynı tanımlayıcıyı düzinelerce kez yazdırmasını önleyen de budur.
Her yerde tek bir ayırıcı dilbilgisi geçerlidir: kardeş hatalar arasında ---, iç içe bağlam çerçeveleri arasında caused by:.
Reddedilen bir katalog dosyası ve açıkladığı hata
Bir Release’in neye bağlı olduğunu çözümlemek için katalog yüklemek bilerek hoşgörülüdür: okunamayan bir dosya ya da ayrıştırılamayan veya dizinlenemeyen bir Aggrega belgesi, yüklemenin tamamı iptal edilmek yerine reddedilir ve kaydedilir. Release’inizin hiç dokunmadığı bozuk bir varlığın ilgisiz bir derlemeyi başarısız kılmasını önleyen budur.
Bunun sonucu, reddedilen bir dosyanın katalogdan sessizce eksilmesidir; Release’iniz ona gerçekten ulaşırsa, başarısız olan şey o dosyanın bildirdiği şeye yapılan bir başvuruyu çözümleme girişimidir. Bu hata reddin kendisi değil, reddin bir sonucudur; bu nedenle rapor, reddi tam olarak adlandırabildiği her yerde ikisini neden-sonuç sırasına koyar:
[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"Ret, kendi kategorisi ve kendi kısa koduyla başta gelir, çünkü üzerinde işlem yapabileceğiniz şeyi adlandırır: düzeltme, bir başvurunun kayıt defterinde nasıl arandığıyla ilgili bir şey değil, bir Recipe’teki eksik implements: öğesidir. Çözümleme hatası yine de altında raporlanır, çünkü o belgenin neden gerekli olduğunu söyleyen odur.
Ret, yalnızca başarısız başvurunun adlandırdığı kimliği tam olarak bir reddedilen dosya bildirdiğinde başta gelir. Eşleştirme, her belgenin kendisi için bildirdiği kimlik üzerinden yapılır: türü, adı, sürümü ve bir recipe için onu kapsamlayan spec.capability; dolayısıyla başvurunun istediğini bildiren reddedilmiş bir dosya, o başvurunun çözümleneceği dosyadır. Bundan iki sonuç çıkar. Bir sürüm yerine sürüm aralığı belirten bir başvuru tek bir belgeyi adlandırmaz, bu yüzden hiçbir şeyi ayırt etmez. Üst bilgisi okunamayacak kadar bozuk bir belge de hiçbir kimlik bildirmez, bu yüzden hiçbir şeyin nedeni olarak adlandırılmaz.
Hiçbir reddedilen dosya o kimliği bildirmiyorsa veya birden fazlası bildiriyorsa, rapor hiç ret kaydı yokmuş gibi olur: hata başta gelir ve her ret, değerlendirmeniz için altında listelenir. Yanlış dosyayı neden olarak adlandırmak hiçbirini adlandırmamaktan daha kötü olurdu, çünkü ona göre hareket ederdiniz.
[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 schemaBu ikinci biçimle ilgili birkaç şeyi bilmekte yarar vardır, çünkü her biri bloğun aksi hâlde doğuracağı bir soruyu yanıtlar.
Baş satır bir reddi değil, hatayı adlandırır. En üstteki kısa kod, çözümleme hatasının oluşturduğu koddur, çünkü burada başta gelen o hatadır; hiçbir reddedilen dosya ayırt edilmediği için hiçbiri satırın başında yer almaz. Yanında kategori bulunmaz, çünkü bu yoldaki hiçbir şey hatayı bir ilgi alanı altında sınıflandırmamıştır. Her reddin kendi baş satırı, altındaki kendi girdisinde yer alır; onu okuyacağınız yer orasıdır.
Yalnızca önemli olan değil, her ret listelenir. Bu biçime ulaşılması, kaydın birini ayırt edemediği anlamına gelir; bu nedenle not tahmin yürütmek yerine ayrımı belirtir: bu Release’in kapanışı dışındaki bir ret hoş görülür ve başarısız olan şey olamaz, bu da Release’in ulaştığı bir şeyi adlandıran reddi, hatayı açıklayan tek girdi olarak bırakır. Girdileri Release’inizin gerçekte kullandıklarıyla karşılaştırarak okuyun.
Her girdi, köşeli parantez içinde kendi baş satırını, yani kendi kategorisini ve kendi kısa kodunu taşır. Bu, tanılamanın baş satırının altında kısa kodun göründüğü tek yerdir ve yukarıdaki devam kuralının bir istisnası değil, onun bir sonucudur: note: altındaki bir girdi, daha içeriden görülen aynı hata değil, farklı bir belgenin oluşturduğu farklı bir durumdur. Durumunu adlandırmak, reddi aramanızı ve dosyayı düzeltmenizi sağlar; bloğun var olma amacı da bu eylemi mümkün kılmaktır.
Başlığı, bildirdiği kimliği kurtarmaya izin vermeyecek kadar bozuk olan reddedilmiş bir dosya yalnızca yoluyla listelenir. Bu, hiçbir şeyin içine göz atamadığı bir belgenin dürüst okumasıdır ve yol, dosyayı açmak için yine de yeterlidir. Türü bile okunamayacak kadar bozuk bir dosya — örneğin YAML olarak ayrıştırılamayan bir dosya — bir Aggrega apiVersion’ı bildirdiğinde, yani girintisiz olarak apiVersion: ile başlayan ve değeri aggrega.ai/ ile başlayan bir satır içerdiğinde, ayrıştırıcının kendi nedeniyle birlikte bu şekilde listelenir: satır ve ayrıştırıcının orada ne beklediği. Başka bir apiVersion bildiren ya da hiç bildirmeyen bir YAML dosyası bir Aggrega belgesi değildir — örneğin bir chart şablonu ya da varlıkların yanında tutulan bir yapılandırma dosyası — bu nedenle ne kadar bozuk olursa olsun hiçbir zaman listelenmez.
Hiçbir kataloğun tutmadığı bir tür bildiren bir dosya yalnızca hatayı açıkladığı yerde adlandırılır. Bir Aggrega apiVersion’ı ve hiçbir kataloğun tutmadığı bir kind bildiren bir belge — örneğin yanlış yazılmış bir Componnent — her yüklemede atlanır; bu nedenle bir ret değildir ve retler arasında listelenmez. Başarısız olan başvuru o dosyanın bildirdiği adı ve başvuru bir sürüm belirtiyorsa o sürümü istediğinde, rapor, başvurunun hangi tür olarak toplandığından bağımsız olarak, dosyayı hatanın altında kendine ait bir notta adlandırır — aşağıda listelenen her yüzeyde ve mevcut bir kilit dosyasını okusun ya da önce bir tane doldursun aggrega build üzerinde:
[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 directoriesHata başta kalmaya devam eder: dosyanın bildirdiği tür hiçbir kimlik belirtmez, bu nedenle dosya, raporun başladığı ret olarak asla öne çıkarılmaz. Yerel varlıkların nereden okunduğuna ilişkin açıklama bu rapordan çıkarılır, çünkü dosya zaten kataloğun okuduğu yerdedir ve onu taşımak yardımcı olmaz. Hiçbir kataloğun tutmadığı türden olup başka bir ad bildiren bir dosya bu hata hakkında hiçbir şey açıklamaz ve anılmaz. İletileri tek satır olan aggrega serve, aynı notu o satırda taşır — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: ve ardından dosyanın reddi — ve böyle bir dosyayı yükleme sırasında atlanan dosyalar arasında asla listelemez; aggrega mcp içindeki describe aracı da bir Release’in koşullarında bir ad sorulduğunda o açıklamanın yerine dosyayı adlandırır. Tüm katalog için aggrega validate ve aggrega lint, herhangi bir şeyin ona ulaşıp ulaşmadığından bağımsız olarak böyle her dosyayı raporlar — bkz. fatal-halts.md §“A catalog document declares a kind a catalog does not hold (Bir katalog belgesi, kataloğun tutmadığı bir tür bildiriyor)”.
Hangi biçimi alırsanız alın, hata kendi kimliğini korur. Not, hatanın üzerine işlenmek yerine hataya eklenir ve bir retle başlamak yalnızca önce neyi okuyacağınızı değiştirir; dolayısıyla hatanın oluşturduğu durum her iki durumda da bozulmadan kalır: kısa kodu yine çözümlenir ve durumla eşleştirme yapan bir araç yine eşleşir.
Reddedilen belge bir komutun raporladığı şeyin kendisiyse, ret bir kez belirtilir. aggrega inspect <name> kataloğu katı biçimde yükler; bu nedenle yüklemenin reddettiği bir belge onu durdurur ve yazdırdığı şey o belgenin reddidir, tek bir tanılama olarak: reddin kategorisini ve kısa kodunu taşıyan baş satır, kaynak olarak belge ve altında belgede neyin yanlış olduğu; bir şema ihlali için ihlal edilen anahtarlar satır ve sütunlarıyla birlikte ve öneri. Bunu oluşturan yükleme, dolaştığı dizinden ve dosyayı okuyan adımdan geçmiştir; bunlar ayrı çerçeveler olarak yazdırılmaz, çünkü her biri hiçbir bilgi eklemeden aynı belgeyi yeniden adlandırırdı. aggrega serve, reddedilen bir belgenin bir adı bildirdiği yerde o adın neye başvurduğu sorulduğunda, aynı reddi aynı sözcüklerle tek satırda yanıtlar ve ardından dosyanın yüklemede atlandığını belirten not gelir. Yukarıda olduğu gibi, reddin durumu her iki durumda da eşleştirilebilir kalır.
Her iki biçim de bu çözümlemenin çalıştığı her yerde size ulaşır. aggrega build, aggrega pull, aggrega validate --release ve aggrega inspect --closure bunları terminalde üretir; implements hedefi bulunamayan tek bir Recipe üzerinde çalıştırılan aggrega validate da öyle. aggrega mcp üzerinden bağlanan bir yapay zekâ asistanı da aynı açıklamayı build ve validate araçlarından alır; reddedilen bir dosyanın bildirdiği bir varlığın catalog:// okumasından ise başta gelen reddi tek satır olarak alır. Hangi yüzeyden sorduğunuz, açmanız için yönlendirildiğiniz dosyayı hiç değiştirmez; aggrega mcp sunucusuna HTTP üzerinden ulaşan bir çağırana dosya çalışma alanı köküne göre bildirilir ve o sunucunun hizmet verdiği çalışma alanının dışındaki bir dosya bildirilmez. Bir retin başta geldiği yerde ise yanıtın işaret ettiği yazım sözleşmesi, başarısız olan başvurunun türü için değil, reddedilen belgenin bildirdiği tür içindir.
Belge zarfı hata sınıfı
Her varlık belgesi (katalog varlıkları, Aggregates, Manifests, Releases) yüklendiğinde, tipli ayrıştırmadan önce kendi türünün yayımlanmış JSON şemasına göre doğrulanır. Zarfını ihlal eden bir belge (bilinmeyen bir anahtar, eksik bir zorunlu alan, yanlış biçimde bir değer, Release values: gibi yasaklanmış bir yapı), önce koşulu, ardından varlık türünü ve dosyayı, sonra hatalı her anahtarı veya biçimi bulunduğu satır ve sütunla, en son da ne yapılması gerektiğini belirten bir tanılamayla açıkça durur:
[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 schemaTanılama koşulla başlar, türü ve dosyayı belirtir ve ne yapılması gerektiğiyle biter; aradaki her ihlal yalnızca line:column taşır, çünkü baş kısım dosyayı zaten belirtmiştir. Hatalı her anahtar, onu içeren bloğun konumunda değil kendi konumunda bildirilir; böylece satır ve sütun, değiştirmeniz gereken anahtarı gösterir. Konumun biçimi şemadaki yeniden kullanılabilir bir tanımdan geliyorsa tanılama, against sözcüğünden sonra o tanımı belirtir (yukarıda against /$defs/boundary); böylece anahtarın hangi sözleşmeye göre ölçüldüğü açıkça anlaşılır ve tanım, yazdığınız anahtar yolunda bir adım daha gibi okunmaz. Birden çok ihlal içeren bir belge her birini kendi konumunda, anahtar sırasıyla listeler ve rapor dört ihlalden sonra kalanların sayısını vererek durur.
Bir konumun nereyi gösterdiğiyle ilgili iki şeyi bilmekte yarar vardır, çünkü ikisi de şaşırtıcı olmaktan çok yararlıdır:
- Eksik bir zorunlu anahtarın kendine ait bir konumu yoktur; tanımı gereği belgede bulunmaz. İhlal bunun yerine kapsayan anahtarı gösterir; eksik girdinin ait olduğu yer de orasıdır. Dolayısıyla
spec.capability: missing required property,spec:anahtarını gösterir ve eklemeniz gereken yer de orasıdır. - Kendi adında nokta bulunan bir anahtar (her
component.aggrega.ai/…etiketi vefeatures.aggrega.ai/…ek açıklaması), girdinin kendisinde değil onu tutan blokta bildirilir, çünkü noktalar belgenin içine doğru adımlar olarak okunur. Bir etiketteki ihlallabels:anahtarını gösterir.
Bir ihlal belgede hiçbir yerde bulunmayan bir anahtarı belirttiğinde (örneğin tümüyle atlanmış bir metadata: bloğu), konum tahmin edilmek yerine atlanır ve ihlal yalnızca anahtar yolu ve iletiden oluşur. Güvenmemeniz gereken bir konum, hiç konum olmamasından daha kötüdür.
Kategori, yazım yüzeyini izler: katalog varlıkları için [CATALOG_ERROR], Aggregates için [DEVELOPER_ERROR], Releases ve Manifests için [OPS_ERROR]. Aynı denetim, varlık yükleyen her yüzeyde çalışır (aggrega build, aggrega lint, aggrega validate ve aggrega serve tarafından yayımlanan düzenleyici tanılamaları); böylece fazladan veya yanlış yazılmış bir anahtar sessizce yok sayılmak yerine belgenin ilk okunduğu yerde reddedilir. Bu yüzeylerin her biri konumu aynı şekilde çözümler, dolayısıyla aynı anahtarı gösterir ve her biri koşulun cümlesini koşulun kendisinden okur: düzenleyicinizin altını çizdiği satır, terminalin belirttiği satırdır ve düzenleyicideki girdinin başladığı cümle, terminalin başladığı cümledir. İki yüzeyin paylaşmadığı şey iletinin tamamıdır ve bu bilinçli bir tercihtir: terminal her bulguyu tek bir başlık altında toplar ve yol için öneriyle biter; düzenleyici ise her bulgu için kendi anahtarına konumlanmış bir girdi üretir ve ne zaten bağlı olduğu dosyayı ne de aksi halde her alt çizgi için bir kez söyleyeceği öneriyi tekrarlar. Böylece örtüşen kısım, koşulu tanıdığınız kısımdır.
Çoklu hata zincirleri
Tek bir derleme birden çok bağımsız ihlal tespit ettiğinde (en sık olarak, herhangi biri derlemeyi durdurmadan önce her seçici ve appliesTo ihlalinin toplandığı statik analiz sırasında), hatalar tek bir zincirde birleştirilir. CLI zinciri dolaşır ve her alt hatayı, yatay çizgi satırıyla ayırarak bağımsız olarak işler:
[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.--- ayırıcısı birebir yazılır; okuyucular ve sonraki araçlar birleştirilmiş hataları tek tek saymak için metni bu ayırıcıdan bölebilir. Her alt hata, komşusunun bir ayrıntısı değil, başlı başına bir hatadır; bu nedenle her biri kendi başlığını taşır: eksik belirteçlerle ilgili bölümün açıkladığı gibi, kendi kategorisi ve kendi kısa kodu, her biri var olduğu yerde. Tek bir kuralın iki ihlali, yukarıdaki gibi aynı kısa kodu belirtir; farklı kuralların iki ihlali ise farklı kodlar belirtir.
Bir hatayı baştan sona okumak
Çoğu yazım bağlamında, kategori öneki ve kaynak işaretçisi birlikte neyin düzeltilmesi gerektiğini belirler:
| Kategori | Düzeltmenin yapılacağı yer | Örnek yüzeyler |
|---|---|---|
[DEVELOPER_ERROR] | Aggregate YAML | Aggregate’in yazdıkları üzerindeki seçici / appliesTo ihlalleri; Aggregate tarafındaki uses soket uyuşmazlığı; geliştirici yazımında çözümleyici durmaları. |
[OPS_ERROR] | Release YAML / Manifest YAML | Sınır yolu şablonunun desteklenmeyen bir alana başvurması; subDirectory alanının yol çakışmasına yol açması; Release yazımında çözümleyici durmaları; Release’in bağladığı bir bağlantının ya da bir bağlantıda doldurduğu bir eklemenin soketin veya yuvanın kurallarınca reddedilmesi; yalnızca Release’in bir bileşene ya da bir sınıra eklediği bir Feature’ın, Feature’ın veya yuvanın kurallarınca reddedilmesi; bir Manifest eşlemesinin veya açıklama bağlamasının reddedilmesi. |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Recipe biçim kuralları; FeatureRecipe şablonunun executionScope: boundary ile yalnızca bileşen başına olan bir alana başvurması; Workload featuresSchema çapraz denetiminin başarısız olması. |
[TRANSLATION_ERROR] | Workload / valuesMapping çıktısı / kaynak katmanı | Helm yoklama portu çözümlemesi; sınırlar arasında compose hizmet adı çakışması; iki compose katkıcısının aynı üst düzey birim veya yapılandırma adını çelişen gövdelerle bildirmesi; helm-chart şemsiyesinde chart adı uyuşmazlığı. |
[FETCH_ERROR] | Kayıt defteri / uzak kaynak edinimi (yazımsal değil, işletimsel) | Yapıtın kayıt defterinde bulunamaması; kimlik doğrulamanın gerekmesi; ağa erişilememesi; önbellekteki özetin kilit dosyasıyla uyuşmaması. Düzeltme: kimlik doğrulayın, bağlantıyı yeniden sağlayın ya da aggrega pull --upgrade --release <release> komutunu çalıştırın. |
[POLICY_ERROR] | Politika plugin’i (yönetişim kuralı) | Bir yönetişim kararı rolüne eklenmiş bir politika plugin’i, birleştirilmiş derlemeyi uyguladığı bir kurala göre reddetti. Düzeltme: uygulanan politikayı karşılayın ya da eklemeyi yeniden değerlendirin. |
[TRUST_ERROR] | Güven yapılandırması ya da yapıtın kendi imzası (bir yazım yüzeyi değil, bir kaygı) | Okunamayan bir güven politikası veya sabitlenmiş güven kökü; hiçbir güvenilir kimlik bildirmeyen anahtarsız bir politika; yayımlanan tür için imza gerektiren bir imzalama politikası; yapılandırmanın artık eklemediği, kaydedilmiş bir karar ekleme kapısı. Ya da: doğrulanmayan bir imza; imza gerektiği hâlde hiç imza taşımayan bir yapıt; güvenilmeyen bir imzalayıcı; kaydedilmiş güvenilir kimliği artık eşleşmeyen bir plugin. Düzeltme: yapılandırmayı ya da kaydedilmiş güven kaydını düzeltin veya yapıt hakkında karar verin; hangisi olduğunu kısa kod söyler. |
Sağlayıcıya özgü bağlam önekleri (helm: node "<id>": ..., compose: node "<id>": ...), birden fazla sağlayıcı devredeyken başarısız olan sağlayıcıyı belirlemek için [TRANSLATION_ERROR] ve [CATALOG_ERROR] çıktılarının ileti bölümünde görünür.
Kütüphaneye özgü hatalar
Alttaki bir kütüphanenin içinde ortaya çıkan hatalar (Helm SDK chart yükleme hataları, docker-compose YAML ayrıştırıcı hataları, eksik bir kaynak yolundan kaynaklanan dosya G/Ç hataları), sağlayıcıya özgü bağlam önekiyle sarmalanır ve sentez sırasında mı yoksa katalog içeriği yüklenirken mi tetiklendiklerine bağlı olarak [TRANSLATION_ERROR] veya [CATALOG_ERROR] altında görünür. Sarmalanan kütüphane mesajı, özgün aracın tanılamasını olduğu gibi korur; böylece yazarlar onu aracın kendi belgeleriyle eşleştirebilir.
Çapraz başvurular
fatal-halts.md— her ölümcül durdurmanın, amaçlanan mesajı ve nasıl düzeltileceğiyle birlikte hata başına kataloğu.warnings.md— derleyicinin yaydığı ölümcül olmayan uyarılar.vocabulary/validation-surface.md— dört şema doğrulama katmanı ve hata biçimlerinin birbiriyle nasıl etkileştiği.