오류 변환 원칙
Aggrega의 컴파일 파이프라인은 여러 지점에서 오류를 내보냅니다. 스키마 검증기, 리졸버, IR 빌더, 프로바이더, Go 템플릿 엔진, 그리고 프로바이더가 감싸는 하위 YAML / Helm / docker-compose 라이브러리가 그 예입니다. CLI까지 올라오는 오류는 최대 두 가지를 명시하는 대괄호 머리말로 시작합니다. 하나는 어느 관심사를 살펴봐야 하는지 알려 주는 범주(대부분의 값에서는 잘못이 있는 작성 영역)이고, 다른 하나는 빌드를 중단시킨 조건의 짧은 코드입니다. 그 뒤에 소스 위치와 메시지가 이어집니다. 플러그인이 조건을 발생시킨 경우 코드는 그 조건을 발생시킨 플러그인으로 한정됩니다. 둘 이상의 플러그인이 같은 조건을 보고할 수 있기 때문입니다. 이 페이지는 작성자가 오류 메시지를 직접 해석할 수 있도록 그 출력의 형태를 설명합니다.
오류별 목록(모든 치명적 중단과 해결 방법 안내)은 fatal-halts.md를 참조하십시오. 네 가지 스키마 검증 계층과 각 계층의 오류 형태가 상호 작용하는 방식은 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 스키마 검증, 경계 경로 템플릿 평가, provider 간subDirectory충돌, Manifest 매핑 및 어노테이션 바인딩 거부, Release가 연결하는 연결 또는 Release가 연결에 채우는 부착을 거부하는 규칙(소켓의 셀렉터, 슬롯의 셀렉터, 소켓이 필수로 선언한 슬롯), Release만 컴포넌트나 경계에 부착하는 Feature를 거부하는 규칙(Feature의appliesTo, 슬롯의 셀렉터, 선언된 스키마).[CATALOG_ERROR]— 실패가 카탈로그 엔티티(Recipe, FeatureRecipe, Component, Feature, Plugin)에 귀속됩니다. 수정할 곳은 카탈로그 내용입니다. 예시 표면: Recipe 형태 규칙, WorkloadfeaturesSchema교차 검사, 카탈로그에서 작성한 템플릿의 템플릿 파싱 오류.[TRANSLATION_ERROR]— 실패가 provider 측 합성(provider 플러그인이 Workload, valuesMapping 출력 또는 소스 오버레이를 provider 고유 아티팩트로 변환하려는 과정)에 귀속됩니다. 수정할 곳은 일반적으로 Workload의services/containers/volumes형태, Recipe의valuesMapping템플릿 출력 또는 소스 모드 오버레이 구조입니다.[FETCH_ERROR]— 실패가 작성 표면이 아니라 레지스트리나 원격 소스에서 고정된 의존성을 가져오는 과정에 귀속됩니다. 수정은 대개 운영상의 조치입니다. 레지스트리에 인증하거나(docker login <registry>), 연결을 복구하거나, 변경되었거나 변조된 아티팩트를 다시 고정합니다(aggrega pull --upgrade --release <release>). 예시 표면: 레지스트리에서 카탈로그 엔티티나 차트를 찾을 수 없음, 인증이 필요하거나 실패함, 네트워크에 연결할 수 없음, 캐시된 아티팩트의 다이제스트가 lockfile과 일치하지 않음. 가져오기 오류는 메시지에 구체적인 해결 방법 안내를 담고 있습니다.[POLICY_ERROR]— 거버넌스 판정 역할에 부착된 정책 플러그인이 빌드를 거부했습니다. 이는 작성 표면의 결함이 아닙니다. 입력은 올바른 형식이지만 플러그인이 시행하는 거버넌스 규칙(컴플라이언스, FinOps 또는 보안)을 통과하지 못한 것입니다. 수정 방법은 작성한 내용을 시행 중인 정책에 맞추거나 정책 부착을 재검토하는 것입니다. 메시지는 거부한 플러그인의 이름과 그 플러그인이 제공한 규칙 메시지를 담고 있습니다.[TRUST_ERROR]— 신뢰 및 서명 계층이 작업을 거부했습니다. 이 범주는 작성 표면이 아니라 관심사를 가리키며, 옆에 있는 짧은 코드로 구별할 수 있는 두 가지 해결책을 포함합니다. 신뢰 구성이 잘못된 경우: 읽을 수 없는 신뢰 정책, 불러올 수 없는 고정된 신뢰 루트, 신뢰하는 ID를 선언하지 않은 keyless 정책, 게시하려는 아티팩트 종류에 서명을 요구하는 서명 정책, 또는 구성에서 더 이상 부착하지 않는 판정 부착에 대해 신뢰된 것으로 기록된 플러그인. 이 아티팩트가 검증에 실패한 경우: 신뢰 앵커에 대해 검증되지 않는 서명, 서명이 필요한데 서명이 없는 아티팩트, 실제 존재하지만 신뢰되지 않은 서명자의 서명, 또는 기록된 신뢰 ID가 현재 해석되는 것과 더 이상 일치하지 않는 플러그인. 첫 번째 경우 수정할 곳은 구성 또는 커밋된 신뢰 기록이며, 두 번째 경우에는 아티팩트에 대한 결정이 필요합니다. 검토된 아티팩트를 복원하거나, 변경된 내용을 검토하고 다시 기록합니다.
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.두 문서가 하나의 부착을 함께 작성하는 경우(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.(Aggregate 또는 Release에서, 컴포넌트 또는 그 상위 범위에 해당 이름으로 Feature를 부착하십시오.)”
에디터도 같은 배치를 따릅니다. Release에 위치한 발견 사항은 Release의 문서에서 그것을 작성한 키 위에 표시되며, Aggregate의 문서에는 전혀 표시되지 않습니다. Aggregate가 가져오는 모듈의 문서에 위치한 발견 사항도 같은 방식으로 그 모듈의 문서에 표시됩니다.
출력 형태
출력되는 진단은 대괄호로 묶인 헤드와 소스 포인터로 시작하며, 메시지는 들여쓴 별도의 줄에 둡니다:
[CATEGORY SHORTCODE] <source> <message>헤드에는 두 개의 토큰이 있으며, 각각 다른 질문에 답합니다. 카테고리는 위에 나온 것 중 하나로, 어떤 관심사를 살펴봐야 하는지 알려 줍니다. 짧은 코드는 문자 E와 네 자리 숫자로 이루어지며, 빌드를 중단시킨 정확한 조건을 가리킵니다. 보고서에 인용하거나, 검색어로 입력하거나, sentinels.md에 있는 모든 조건의 표에서 확인할 수 있습니다. 둘 중 어느 것도 다른 하나로부터 도출할 수 없으므로 둘 다 출력됩니다. 또한 [TRUST_ERROR]처럼 하나의 카테고리가 여러 해결 방법을 포괄하는 경우, 그중 어느 경우에 해당하는지 알려 주는 것은 짧은 코드입니다.
플러그인이 발생시킨 코드는 그 코드를 발생시킨 플러그인으로 한정됩니다
모든 짧은 코드는 Aggrega가 선언하는 조건을 가리키며, 두 조건이 하나의 코드를 공유하는 일은 없습니다. 다른 조건이 이미 가진 번호로 선언된 조건은 컴파일러가 어떤 입력을 읽기도 전에 거부됩니다. 플러그인은 자체 코드를 할당하지 않습니다. 플러그인은 실패를 보고할 때 Aggrega가 선언하는 조건 중 하나(플러그인이 어떻게 실패했는지를 설명하는 몇 가지 일반 조건 중 하나, 또는 해당하는 경우 더 구체적인 조건)를 지정하고, 실제로 무슨 일이 일어났는지를 말하는 문장을 제공합니다. 따라서 두 플러그인이 같은 짧은 코드를 보고할 수 있으며, 그럴 때 둘은 같은 조건을 보고하는 것입니다.
코드가 알려 줄 수 없는 것은 어느 플러그인이 그 조건을 만났는지이며, 플러그인이 발생시킨 조건을 보고하는 헤드는 코드 바로 앞에 플러그인의 식별자를 표시합니다:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>짧은 코드는 항상 마지막 세그먼트입니다 — 마지막 / 뒤에 오는 문자 E와 네 자리 숫자입니다. 플러그인의 식별자에는 자체 구분자가 포함되며 버전이 포함될 수도 있으므로, 첫 번째 /부터가 아니라 끝에서부터 읽어야 어떤 헤드에서든 코드를 찾아낼 수 있습니다. 마지막 세그먼트 앞의 모든 부분은 플러그인입니다.
마지막 세그먼트는 어느 플러그인이 발생시켰든 다른 짧은 코드와 똑같이 확인됩니다. sentinels.md의 모든 조건 표에 나열되어 있으며 aggrega explain으로 확인할 수 있습니다. 마지막 세그먼트만 인용하십시오. 한정자는 어느 플러그인이 그 조건을 만났는지를 알려 줄 뿐, 그것이 어떤 조건인지를 알려 주지는 않습니다. Aggrega가 선언하지 않은 코드(어떤 조건도 가지지 않은 번호 또는 폐기된 번호)를 지정한 플러그인의 경우 그 코드는 출력되지 않습니다. 빌드는 해당 플러그인으로 한정된 E0293에서 중단되며, 그 메시지는 플러그인이 제시한 코드를 인용하고, 앞서 말한 일반 조건들을 명시하며, 플러그인 자체의 문장을 유지합니다.
짧은 코드만 출력하는 헤드는 Aggrega 자체가 발생시킨 조건을 보고하는 것이며, 여기에는 플러그인이 실패했지만 자체 조건을 지정하지 않은 경우도 포함됩니다. 이 경우 빌드를 중단시킨 것은 컴파일러의 일반적인 플러그인 실패 조건이며, 세부 내용은 플러그인의 메시지에 담겨 있습니다.
두 토큰 모두 없을 수 있으며, 없는 토큰은 생략됩니다
진단에 없는 토큰을 대신하는 것은 결코 없습니다. 자리 표시자도, 빈 대괄호도 없습니다. 헤드가 짧아지는 경우는 세 가지이며, 각각 알려 주는 바가 있습니다:
- 짧은 코드가 없는 경우. 실패가 Aggrega 자체의 조건을 지정하지 않는 경우로, 대부분 컴파일러가 래핑하는 라이브러리가 보고한 오류입니다. 헤드에는 카테고리만 출력되므로, 여전히 어느 영역을 살펴봐야 하는지 알 수 있습니다.
- 카테고리가 없는 경우. 실패에 안내할 관심사가 없으므로 추측하지 않습니다. 헤드에는 짧은 코드만 출력되며, 확인할 대상은 그 코드입니다. 이런 경우는 두 가지 상황에서 발생하며, 사용자 입장에서는 같으므로 같은 모양으로 보입니다. 둘 다 어디를 살펴봐야 할지 알려 주지 않으며, 무슨 일이 일어났는지는 코드가 알려 줍니다. 하나는 컴파일러 자체의 결함으로, 메시지가 그렇다고 밝히고 보고를 요청합니다. 실제로 발생하는 사례는 카탈로그에 대한 컴파일러 내부의 뷰들이 서로 일치하지 않는 경우입니다. 다른 하나는 조건을 지정하지만 그것을 관심사로 분류하는 영역을 거치지 않은 실패로, 명령 경계에서 발생한 거부가 보통 이런 형태입니다. 빈자리를 채우기 위해 카테고리를 만들어 내는 일은 없습니다. 이는 생략의 한계가 아니라 생략의 목적입니다. 카테고리는 “어떤 관심사를 살펴봐야 하는가”에 대한 답이며, 질문에 답이 없는 곳에 제시된 답은 신중한 답이 아니라 잘못된 답이고, 그것이 가장 먼저 실행에 옮겨집니다. 또한 반대 방향의 추론은 성립하지 않는다는 점도 짚어 둘 만합니다. 카테고리를 가진 헤드라고 해서 항상 직접 작성한 무언가를 가리키는 것은 아닙니다.
[FETCH_ERROR],[POLICY_ERROR],[TRUST_ERROR]는 각각 작성 영역이 아니라 관심사를 나타내기 때문입니다. - 둘 다 없는 경우. 대괄호가 완전히 생략되며 진단은 메시지 그 자체입니다. 이는 Aggrega 자체의 조건을 지정하지 않으면서 동시에 안내할 관심사도 없는 실패입니다. 인수를 거부하는 명령, 읽을 수 없는 파일, 취소, 또는 그 아래에 우리의 조건이 전혀 없이 컴파일러가 래핑하는 라이브러리가 보고한 오류가 이에 해당합니다.
sentinels.md에서 확인할 것이 없으며, 메시지가 그 실패가 전하는 내용의 전부입니다.
같은 오류를 한 줄로 줄인 형태는 터미널이 아닌 로그 출력에 적합하며, 카테고리는 유지하고 짧은 코드는 제외합니다:
[CATEGORY] <source>: <message>헤드에 없는 카테고리는 여기에서도 대괄호까지 포함해 없으므로, 이 줄은 결코 [] <source>: <message>가 되지 않습니다. 한 줄 형태는 실패가 위로 전파되면서 바깥 프레임에 다시 래핑되므로, 빈 태그가 있다면 그 모든 프레임에 전달될 것입니다.
소스는 구조화된 포인터입니다. YAML 위치를 알 수 있으면 보통 <file>:<line>:<column>이고, 파일 위치가 적용되지 않으면 논리적 식별자(카탈로그 엔티티 이름, Release 이름, 경계 경로)입니다. 세 번째 형태인 <file> at <key>는 포인터가 문서와 그 안의 작성 키는 알지만 바이트 위치는 모를 때 나타납니다. 파일은 열어야 할 대상이고, 키는 연 다음 살펴봐야 할 곳입니다. 메시지는 영역별 진단입니다.
빌드의 한 인스턴스, 즉 컴포넌트, 모듈이 제공하는 컴포넌트 또는 모듈 자체에 관한 실패는 위치 뒤에 (instance <name>) 형태로 그 인스턴스를 지목합니다. 따라서 aggregate.yaml (instance shop)은 모듈 shop을 선언하는 Aggregate를 뜻합니다. 실패가 가리킬 문서가 없으면 인스턴스는 instance <name>으로 단독으로 나타납니다. 컴포넌트 adminer를 렌더링하다 실패한 프로바이더는 [TRANSLATION_ERROR E0082] instance adminer를 출력하며, 그 아래 줄들이 실패가 지목하는 문서를 포함한 나머지 내용을 담습니다. 이름은 Aggregate가 컴포넌트를 선언할 때 쓴 이름이며, 모듈이 제공하는 컴포넌트는 shop.cart처럼 모듈을 거치는 경로로 이름이 붙습니다. 파일이 와야 할 자리에 인스턴스가 출력되는 일은 없으므로, 소스 포인터의 맨 앞에 오는 것은 언제나 열 수 있는 문서이거나 위에서 설명한 논리 식별자 중 하나입니다.
완성된 그래프를 대상으로 평가되는 규칙은 이 세 번째 형태로 보고하며, 메시지만으로 두 결과를 구별할 수 없을 때 이를 구별해 주는 것이 키입니다. 이런 종류의 규칙은 인스턴스가 아니라 선언하는 컴포넌트 유형을 지정하므로, 같은 유형의 두 컴포넌트가 같은 규칙을 위반하면 같은 파일에 대한 같은 메시지를 갖게 됩니다:
[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")다른 부분은 키뿐이며, 두 컴포넌트 중 어느 것을 수정해야 하는지 알려 주는 것이 키입니다. 두 결과가 같은 짧은 코드를 갖는 이유는 같은 조건을 두 번 만났기 때문입니다. 짧은 코드는 규칙을 가리키고, 키는 발생 위치를 가리킵니다.
이를 채울 컨텍스트를 가진 실패에는 이 형태에 두 줄이 더 추가됩니다. 실패한 템플릿 표현식과, 실패한 지점에서 범위 내에 있던 필러의 스냅샷입니다:
[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 안에서 거부된 템플릿은 세 표면을 거칩니다. 렌더링 중인 노드, 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)앞에서처럼 위에서 아래로 읽되, 추가된 깊이로 드러나는 세 가지에 주목하십시오. 짧은 코드는 헤드에 한 번만 나타납니다. 뒤따르는 연속 줄이 몇 개든 마찬가지입니다. 조건 자체의 문장은 가장 안쪽 프레임에 있습니다. 따라서 가장 깊은 줄이 매칭할 줄이자 무엇을 바꿔야 하는지 알려 주는 줄입니다. 그리고 소스 포인터가 없는 프레임은 범주만 출력합니다. 위의 가운데 프레임은 실패한 표면을 메시지 안에서 명명합니다. 그 표면은 파일이 아니라 템플릿이어서 가리킬 위치가 없기 때문입니다.
실패가 어떤 프레임 아래에서 갈라지는 경우, 즉 어떤 단계가 중단하기 전에 서로 독립적인 위반을 여러 개 수집한 경우, 연속 줄에는 개수가 표시되고 수집된 모든 실패가 그 아래에 렌더링되며, 아래의 다중 오류 체인과 같은 --- 구분선으로 구분됩니다:
[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개수 아래에 수집된 실패들도 연속 줄이므로, 어느 것도 헤드의 짧은 코드를 반복하지 않습니다. 덕분에 위반 열두 개로 갈라진 경우에도 같은 식별자가 열두 번 출력되지 않습니다.
전체에 걸쳐 하나의 구분자 문법이 적용됩니다. 형제 실패 사이에는 ---, 중첩된 컨텍스트 프레임 사이에는 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:이지, 레지스트리에서 참조를 조회하는 방식에 관한 것이 아닙니다. 해석 실패도 그 아래에 여전히 보고됩니다. 애초에 그 문서가 왜 필요했는지를 알려 주는 것이 바로 이 실패이기 때문입니다.
실패한 참조가 지목하는 식별자를 선언한 거부된 파일이 정확히 하나일 때만 거부가 앞에 옵니다. 일치 여부는 각 문서가 스스로 선언하는 식별자, 즉 종류, 이름, 버전, 그리고 recipe의 경우 범위를 정하는 spec.capability를 기준으로 판단합니다. 따라서 참조가 요구하는 것을 선언한 거부된 파일은 그 참조가 해석되었을 파일입니다. 여기서 두 가지 결과가 따릅니다. 버전이 아니라 버전 범위를 명시한 참조는 단일 문서를 지목하지 않으므로 아무것도 특정하지 않습니다. 그리고 헤더를 읽을 수 없을 만큼 형식이 잘못된 문서는 식별자를 전혀 선언하지 않으므로 어떤 것의 원인으로도 지목되지 않습니다.
그 식별자를 선언한 거부된 파일이 없거나 둘 이상이면, 보고서는 거부 기록이 없을 때와 같습니다. 실패가 앞에 오고, 모든 거부가 그 아래에 나열되어 직접 판단할 수 있습니다. 잘못된 파일을 원인으로 지목하는 것은 아무것도 지목하지 않는 것보다 나쁩니다. 그것을 근거로 조치하게 되기 때문입니다.
[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이 두 번째 형태에 대해 알아 둘 만한 점이 몇 가지 있습니다. 각각이 이 블록을 보고 생길 질문에 답하기 때문입니다.
헤드는 거부가 아니라 실패를 지목합니다. 맨 위의 짧은 코드는 해석 실패가 발생시킨 코드입니다. 여기서는 그 실패가 앞에 오기 때문입니다. 어떤 거부된 파일도 특정되지 않았으므로 어느 것도 그 줄의 헤드가 되지 않습니다. 옆에 카테고리가 없는 것은 이 경로의 어떤 것도 그 실패를 특정 관심사로 분류하지 않았기 때문입니다. 각 거부의 헤드는 아래의 각 항목에 있으며, 거기서 읽으면 됩니다.
중요했던 하나만이 아니라 모든 거부가 나열됩니다. 이 형태에 도달했다는 것은 기록이 하나를 특정할 수 없었다는 뜻이므로, note는 추측하는 대신 구분 기준을 밝힙니다. 이 Release의 closure 밖에 있는 거부는 허용되며 실패 원인일 수 없으므로, Release가 도달하는 대상을 지목하는 거부만이 실패를 설명하는 항목으로 남습니다. Release가 실제로 사용하는 것과 대조하며 항목을 읽으십시오.
각 항목에는 대괄호로 묶인 자체 헤드, 즉 자체 카테고리와 자체 짧은 코드가 있습니다. 진단의 헤드 아래에 짧은 코드가 나타나는 곳은 여기뿐이며, 이는 위의 continuation 규칙의 예외가 아니라 그 결과입니다. note: 아래의 항목은 더 안쪽에서 본 같은 실패가 아니라 다른 문서가 발생시킨 다른 조건입니다. 그 조건을 지목해야 거부를 찾아보고 파일을 고칠 수 있으며, 이것이 이 블록이 존재하는 목적입니다.
헤더의 형식이 너무 잘못되어 선언한 식별자를 복구할 수 없는 거부된 파일은 경로만으로 나열됩니다. 이는 아무것도 들여다볼 수 없었던 문서를 정직하게 읽은 결과이며, 경로만으로도 파일을 여는 데는 충분합니다. 종류조차 읽을 수 없을 만큼 형식이 잘못된 파일(예: 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실패가 계속 맨 앞에 옵니다. 파일이 선언하는 종류는 어떤 식별 정보도 이루지 않으므로, 그 파일이 보고서 맨 앞에 오는 거부로 지목되는 일은 없습니다. 로컬 엔터티를 어디에서 읽는지에 대한 설명은 그 보고서에서 빠집니다. 파일이 이미 카탈로그가 읽는 위치에 있어 옮겨도 도움이 되지 않기 때문입니다. 어떤 카탈로그에도 없는 종류이면서 다른 이름을 선언하는 파일은 이 실패에 대해 아무것도 설명하지 않으므로 언급되지 않습니다. 메시지가 한 줄인 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는 실패 위에 덮어 렌더링되는 것이 아니라 실패에 추가되며, 거부를 앞에 두는 것은 먼저 읽는 내용만 바꿉니다. 따라서 실패가 발생시킨 조건은 어느 쪽이든 그대로 유지됩니다. 짧은 코드는 여전히 해석되고, 조건으로 매칭하는 도구도 여전히 매칭됩니다.
거부된 문서 자체가 명령이 보고하는 대상이면, 거부는 한 번만 표시됩니다. aggrega inspect <name>은 카탈로그를 엄격하게 로드하므로 로드가 거부하는 문서가 있으면 중단되며, 출력하는 것은 그 문서의 거부를 담은 단일 진단입니다. 헤드에는 거부의 카테고리와 짧은 코드가, 소스로는 그 문서가 있고, 그 아래에 문서의 문제점이 나옵니다. 스키마 위반이라면 위반한 키와 그 줄·열, 그리고 조언입니다. 이를 발생시킨 로드는 순회하던 디렉터리와 파일을 읽은 단계를 거쳤지만, 이들은 별도의 프레임으로 출력되지 않습니다. 각각이 사실을 더하지 않고 같은 문서를 다시 지목할 뿐이기 때문입니다. aggrega serve는 거부된 문서가 선언한 이름이 무엇을 가리키는지 질문받으면, 같은 거부를 같은 문구로 한 줄에 답하고 이어서 파일이 로드 시 건너뛰어졌다는 note를 붙입니다. 위와 마찬가지로 거부의 조건은 어느 쪽이든 매칭 가능합니다.
두 형태 모두 그 해석이 실행되는 곳이면 어디서든 전달됩니다. aggrega build, aggrega pull, aggrega validate --release, aggrega inspect --closure는 터미널에서 이를 출력하며, implements 대상을 찾을 수 없는 Recipe 하나에 대한 aggrega validate도 마찬가지입니다. aggrega mcp로 연결된 AI 어시스턴트는 build와 validate 도구에서 같은 내용을 받고, 거부된 파일이 선언하는 엔터티를 catalog://로 읽으면 앞에 오는 거부를 한 줄로 받습니다. 어느 표면에서 요청했든 열어야 할 파일은 달라지지 않습니다. HTTP로 aggrega mcp에 접근하는 호출자는 워크스페이스 루트 기준 상대 경로로 안내받으며, 그 서버가 제공하는 워크스페이스 밖의 파일은 안내받지 않습니다. 그리고 거부가 앞에 오는 경우, 답이 가리키는 작성 계약은 실패한 참조의 종류가 아니라 그 거부된 문서가 선언한 종류에 대한 것입니다.
문서 엔벨로프 실패 유형
모든 엔티티 문서(카탈로그 엔티티, Aggregates, Manifests, Releases)는 로드될 때 타입 지정 파싱에 앞서 해당 종류의 공개된 JSON 스키마에 대해 검증됩니다. 엔벨로프를 위반하는 문서(알 수 없는 키, 누락된 필수 필드, 잘못된 형태의 값, 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). 이렇게 하면 키가 어떤 계약에 대해 검사되었는지 분명해지고, 그 정의가 작성한 키 경로의 한 단계처럼 읽히지 않습니다. 위반이 여러 개인 문서는 각 위반을 해당 위치에 키 순서대로 나열하며, 보고는 네 개 이후에 나머지 개수를 표시하고 멈춥니다.
위치가 가리키는 곳에 대해 알아 둘 만한 점이 두 가지 있습니다. 둘 다 의외라기보다는 유용한 동작입니다.
- 누락된 필수 키에는 자체 위치가 없습니다. 정의상 문서에 존재하지 않기 때문입니다. 대신 위반은 그 키를 감싸는 키를 가리키며, 그곳이 누락된 항목이 들어가야 할 곳입니다. 따라서
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가 게시하는 에디터 진단)에서 동일한 검사가 실행되므로, 잘못 들어갔거나 철자가 틀린 키는 조용히 무시되지 않고 문서가 처음 읽히는 곳에서 거부됩니다. 이들 각각은 위치를 같은 방식으로 산출하므로 같은 키를 가리키며, 각각 조건의 문장을 조건 자체에서 읽어 옵니다. 에디터가 밑줄을 긋는 줄은 터미널이 밝히는 줄이고, 에디터 항목이 시작하는 문장은 터미널이 시작하는 문장과 같습니다. 두 곳이 공유하지 않는 것은 메시지 전체이며, 이는 의도된 것입니다. 터미널은 모든 발견 사항을 하나의 머리글 아래 묶고 해당 경로에 대한 조언으로 끝나는 반면, 에디터는 발견 사항마다 해당 키에 위치한 항목을 하나씩 내보내며, 이미 연결된 파일이나 밑줄마다 반복하게 될 조언은 되풀이하지 않습니다. 따라서 일치하는 부분은 조건을 알아보는 데 쓰는 부분입니다.
다중 오류 체인
한 번의 컴파일에서 서로 독립적인 위반이 여러 개 감지되면(가장 흔한 경우는 정적 분석 중으로, 이때는 어느 하나가 빌드를 중단하기 전에 모든 셀렉터 및 appliesTo 위반이 수집됩니다), 오류들은 하나의 체인으로 결합됩니다. 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.--- 구분자는 문자 그대로 출력되므로, 읽는 사람과 다운스트림 도구는 이를 기준으로 분할하여 결합된 오류들을 열거할 수 있습니다. 각 하위 오류는 이웃한 오류의 세부 사항이 아니라 그 자체로 하나의 실패이므로, 각각 자체 헤드를 가집니다. 즉 누락된 토큰에 관한 섹션에서 설명하듯, 자체 카테고리와 자체 단축 코드를 각각 있는 경우에 가집니다. 위의 예처럼 하나의 규칙에 대한 두 위반은 같은 단축 코드를 나타내고, 서로 다른 규칙에 대한 두 위반은 서로 다른 단축 코드를 나타냅니다.
오류를 처음부터 끝까지 읽기
대부분의 작성 상황에서는 범주 접두사와 소스 포인터를 함께 보면 무엇을 고쳐야 하는지 알 수 있습니다.
| 범주 | 수정할 위치 | 예시 상황 |
|---|---|---|
[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 서비스 이름 충돌, 두 compose 기여자가 하나의 최상위 볼륨 또는 config 이름을 서로 충돌하는 본문으로 선언함, helm-chart 엄브렐라의 차트 이름 불일치. |
[FETCH_ERROR] | 레지스트리 / 원격 소스 획득(작성이 아닌 운영 문제) | 레지스트리에서 아티팩트를 찾을 수 없음, 인증 필요, 네트워크 연결 불가, 캐시된 다이제스트가 lockfile과 불일치. 수정: 인증하거나, 연결을 복구하거나, aggrega pull --upgrade --release <release>를 실행합니다. |
[POLICY_ERROR] | 정책 플러그인(거버넌스 규칙) | 거버넌스 판정 역할에 첨부된 정책 플러그인이 자신이 시행하는 규칙에 따라 조립된 빌드를 거부함. 수정: 시행되는 정책을 충족하거나 첨부를 재검토합니다. |
[TRUST_ERROR] | 신뢰 구성 또는 아티팩트 자체의 서명(작성 대상이 아닌 관심사) | 읽을 수 없는 신뢰 정책 또는 고정된 신뢰 루트, 신뢰할 수 있는 ID를 선언하지 않은 키리스 정책, 게시되는 종류에 서명을 요구하는 서명 정책, 구성이 더 이상 첨부하지 않는 기록된 판정 첨부 게이트. 또는: 검증되지 않는 서명, 서명이 필요한데 서명이 없는 아티팩트, 신뢰할 수 없는 서명자, 기록된 신뢰 ID가 더 이상 일치하지 않는 플러그인. 수정: 구성이나 커밋된 신뢰 기록을 수정하거나 아티팩트에 대해 결정합니다. 어느 쪽인지는 짧은 코드가 알려 줍니다. |
프로바이더별 컨텍스트 접두사(helm: node "<id>": ..., compose: node "<id>": ...)는 [TRANSLATION_ERROR] 및 [CATALOG_ERROR] 출력의 메시지 부분 안에 나타나며, 둘 이상의 프로바이더가 관여할 때 실패한 프로바이더를 특정합니다.
라이브러리 고유 오류
기반 라이브러리 내부에서 발생한 오류(Helm SDK 차트 로드 오류, docker-compose YAML 파서 오류, 소스 경로 누락으로 인한 파일 I/O 오류)는 provider별 컨텍스트 접두사로 감싸지며, 합성 중에 발생했는지 카탈로그 콘텐츠 로드 중에 발생했는지에 따라 [TRANSLATION_ERROR] 또는 [CATALOG_ERROR] 아래에 나타납니다. 감싸진 라이브러리 메시지는 원래 도구의 진단 내용을 그대로 보존하므로, 작성자는 이를 해당 도구 자체의 문서와 대조할 수 있습니다.
상호 참조
fatal-halts.md— 모든 치명적 중단을 오류별로 정리한 목록으로, 의도된 메시지와 해결 방법을 함께 제공합니다.warnings.md— 컴파일러가 내보내는 치명적이지 않은 권고입니다.vocabulary/validation-surface.md— 네 가지 스키마 검증 계층과 각 계층의 오류 형태가 상호 작용하는 방식입니다.