# 실패 메시지와 고칠 파일
기능을 만들 때 흔히 보는 실패 메시지다. 메시지는 코드의 문자열을 그대로 옮겼다. `<...>`는 실제 값이 들어가는 자리다.
찾는 법: 메시지 앞부분으로 이 문서를 검색한다. 없으면 `git grep '<메시지 앞부분>' -- src scripts`로 코드를 찾는다. 코드가 정본이다.
메시지가 어느 단계에서 나오는지:
```text
create:feature → 명령이 파일을 쓰기 전에 거부
generate:feature-index → 모든 빌드·검사 명령이 먼저 돌린다
조립·모듈 로드 → 테스트, 빌드, 앱 부팅 어디서든
check:registries → FE-GATE-010
lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
문서·접근성 → FE-GATE-017, FE-GATE-009, FE-GATE-028
릴리스 승인·공급망 → FE-GATE-027, FE-GATE-012
제거 드릴 → FE-GATE-020
```
``는 기능 ID에서 끝의 `-feature`를 뗀 것이다.
---
## 생성 명령 (create:feature)
모두 `create:feature: ` 뒤에 나온다. 종료 코드는 1이다(인자 오류는 2).
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `feature id "" must be kebab-case (lower-case words joined by single hyphens), at most 40 characters` | ID 형식 | 명령 인자 |
| `context id "" must be kebab-case (lower-case words joined by single hyphens), at most 64 characters` | `--context` 형식 | 명령 인자 |
| `feature id is already a feature or context` | 같은 ID가 있다 | 다른 ID |
| `feature id would prefix its ids with "", which already uses` | 접두어가 기존 기능과 같다 | 다른 ID |
| `context already exists; pass --context to add the feature to it` | 새로 만들 context가 이미 있다 | `--context `를 준다 |
| `context id is a feature id` | context ID가 기능 ID와 같다 | 다른 `--context` |
| `src/contexts has a directory without a context declaration` | 선언 없는 context 폴더 | `src/contexts//context-module.ts`를 만들거나 폴더를 지운다 |
| `another context already owns the route root /*` | 같은 라우트 루트를 다른 context가 가진다 | 다른 ID, 또는 그 context에 `--context`로 넣는다 |
| `a new context needs exactly one deployable app (declared: ); pass --context ` | 앱이 여럿이라 새 context의 소속을 정할 수 없다 | `--context` |
| `route (, ) collides with installed route (, )` | route ID·경로·chunk가 겹친다 | 다른 ID |
| `message keys already exist: ` | 문구 키가 겹친다 | 다른 ID |
| `generated topic is already installed; run the command again` | 무작위 topic이 우연히 겹쳤다 | 명령을 다시 돌린다 |
| `contract package @ is not a pinned identity: ` | 패키지 신원 형식. `` 예: `: package version must be exact SemVer`, `: package digest`, `: package sourceRevision`, `: packageId` | `--package`, `--digest`, `--revision` |
| `--package, --digest and --revision go together. ...` | 셋 중 일부만 줬다 | 셋을 함께 준다 |
| `--package must be @scope/name@. ...` | 버전 없는 패키지 이름 | `@scope/name@1.2.3` 꼴 |
| `--keyed needs --with-create. ...` | `--keyed`만 줬다 | `--with-create --keyed` |
| `refusing to overwrite: ` | 쓸 파일이나 기능 폴더가 이미 있다 | 그 경로를 확인하고 지우거나 다른 ID |
| `the feature index generator rejected the feature, nothing was kept:` | 생성기가 거부했다. 만든 파일은 모두 지웠다 | 뒤따르는 생성기 메시지(아래 절) |
---
## 생성기 (generate:feature-index)
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `Feature belongs to undeclared context ` | context 선언이 없거나 `FEATURE_CONTEXT_ID` 오타 | `src/contexts//context-module.ts`, 또는 `src/features//feature-module.ts` |
| `Context belongs to undeclared app ` | `CONTEXT_APP_ID` 오타 | `src/contexts//context-module.ts` |
| ` must export a literal ` | 헤더를 상수 참조나 식으로 썼다. 생성기는 글자로 읽는다 | 그 파일. `export const = "<값>";` 꼴 |
| ` must export a positive integer ` | 예산 값이 정수 리터럴이 아니다 | 그 파일 |
| `src/features/ has no feature-module.ts; add one or mark the directory with NOT_A_FEATURE` | 기능 폴더에 선언 파일이 없다 | `feature-module.ts`를 만들거나, 기능이 아닌 샘플 폴더면 `NOT_A_FEATURE` 파일을 둔다 |
| `src/features/ has both feature-module.ts and NOT_A_FEATURE; …` | 기능이 아니라고 표시한 폴더에 선언 파일이 있다 | 기능으로 설치하려면 `NOT_A_FEATURE`를 지운다. 설치하지 않으려면 `feature-module.ts`를 지운다 |
| `Duplicate generated feature ids: ` | 두 폴더가 같은 `FEATURE_MODULE_ID` | 한쪽 `feature-module.ts` |
| `Duplicate context id: ` | 두 폴더가 같은 `CONTEXT_MODULE_ID` | 한쪽 `context-module.ts` |
| `Context feature cardinality exceeds budget ` | context의 기능 수가 예산을 넘었다 | `CONTEXT_MAX_FEATURES`, 또는 새 context |
| `App context cardinality exceeds budget ` | 앱의 context 수가 예산을 넘었다 | `src/apps//app-module.ts`의 `APP_MAX_CONTEXTS` |
---
## 조립·모듈 로드
테스트, 빌드, 앱 부팅 어디서든 나온다. 한 기능의 실수가 거의 모든 게이트를 같이 실패시킨다. 첫 메시지를 본다.
### 인증 프로필
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `/: unknown authProfileId ` (계약 조립 오류의 `reason`) | 없는 인증 프로필 | `contracts/-contract-contribution.ts`의 `frontend.authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` |
| `/: with cookie profile must require x-csrf-token or x-xsrf-token` (계약 조립 오류의 `reason`) | 쿠키 인증 프로필로 쓰기 요청을 보내는데 프로필이 CSRF 헤더를 요구하지 않는다 | `src/contracts/product-contracts.ts`의 그 프로필 `requiredCredentialHeaders`. 짝 백엔드는 `x-xsrf-token` |
| `Product REST auth profile reuses a template profile id.` | 제품 프로필 ID가 템플릿 것과 같다 | `src/contracts/product-contracts.ts` |
### 계약·스키마·mapper
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| 부팅 화면 `CONTRACT_SET_PACKAGE_MISSING` / `CONTRACT_SET_PACKAGE_UNEXPECTED`(`corepack pnpm dev`, dev server를 쓰는 브라우저 테스트) | dev manifest `public/release-manifest.json`의 계약 패키지가 설치된 기능과 다르다. 기능을 손으로 더하거나 지웠다 | `node scripts/write-dev-release-manifest.ts`로 다시 쓰고 커밋한다. `tests/unit/dev-release-manifest.test.ts`가 같은 어긋남을 잡는다 |
| `Invalid or duplicate schema definition: ` | 스키마 ID 중복 또는 메타 형식 | `contracts/-schema-metadata.ts`. 접두어를 붙인다 |
| `duplicate operation: ` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/-contract-contribution.ts`. 접두어를 붙인다 |
| `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`, `problemSchema`도 같은 꼴. 실패 본문 행은 `boundary: "api-problem"`) | `contracts/-schema-metadata.ts` |
| `: row , used as ` (`tests/unit/schema-metadata-policy.test.ts`) | 스키마 메타 행의 `boundary`가 그 스키마가 쓰인 자리와 다르다. `no FE-REG-SCHEMA row`는 쓰이는데 행이 없다 | `contracts/-schema-metadata.ts` |
| ` : row states no direction, used as ` 또는 `row states no unknownFieldPolicy, validator ` (`tests/unit/schema-metadata-policy.test.ts`) | descriptor가 쓰는 스키마의 행이 `direction`·`unknownFieldPolicy`를 적지 않았다(1106/07-02) | `contracts/-schema-metadata.ts`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다 |
| `Unregistered route codec: ` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/-routes.ts` |
| `contract package is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/-contract-contribution.ts`의 `source` |
| ` contributes contract package , which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `_CONTRACT_PACKAGE` 하나를 쓰게 한다 |
| `contract package is declared with conflicting identities` | 두 기능이 같은 패키지를 다른 버전·digest로 선언했다 | 두 기능의 `_CONTRACT_PACKAGE`를 맞춘다 |
계약 조립 실패의 메시지는 `Installed contract contribution is not composable: `이다. `reason`은 오류 객체(`ContractContributionError`)의 `reason` 속성에도 있다.
| `reason` | 원인 | 고칠 곳 |
|---|---|---|
| `: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE` | 참조 기능 전용 출처를 다른 기능이 썼다 | `contracts/-contract-contribution.ts`의 `source`를 `EXTERNAL_PACKAGE`로 |
| `duplicate operation: ` | 두 기여가 같은 operation ID | 접두어를 붙인다 |
| `duplicate contributionId: ` | 두 기여가 같은 `contributionId` | `contracts/-contract-contribution.ts` |
| `/: unknown authProfileId ` | V3 `frontend.authProfileId`가 없는 프로필 | V3 `frontend.authProfileId` |
| `/: retry budget contradicts NEVER retry semantics` | `NEVER`인데 `retryBudget`가 0이 아니다 | V3 `frontend.retryBudget` |
| `/: KEYED commands require a recovery descriptor` | `KEYED`인데 `commandRecovery`가 없다 | V3 `commandRecovery` |
| `/: is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>` | 읽기에 `KEYED`나 `NEVER`를 적었다 | V3 `retrySemantics`. 재시도를 막으려면 `frontend.retryBudget: 0` |
| `/: command operations require a command effect descriptor` | 쓰기에 `commandEffect`가 없다 | V3 `commandEffect` |
| `/: refusedBeforeWrite cannot declare ; contract 6.1 reads this platform code as possibly raised after the write` | `commandEffect.refusedBeforeWrite`에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 플랫폼 code(`BAD_PARAMETER`, `DB_*` 등)를 적었다 | 그 code를 목록에서 지운다. 그 실패는 결과 불명으로 남는다([02 결정표 4절](../02-decision-tables.md#4-결과-불명)) |
| `/: read operations carry no command descriptors` | GET에 `commandEffect`·`commandRecovery`를 적었다 | 둘 다 `null` |
| `/: responseEnvelope NONE, but in the same contribution reads ENVELOPE_V1; ...` | 한 계약 기여 안에서 operation 하나만 응답 모양이 다르다. 손으로 더한 operation에 `"NONE"`을 적었거나, TypeScript 밖에서 만든 descriptor가 줄을 뺐다 | 그 operation에 `responseEnvelope: "ENVELOPE_V1" as const`를 적는다. 정말 다른 백엔드면 기여를 나눈다 |
| `check:types`: `Property 'responseEnvelope' is missing in type ...` (descriptor의 `satisfies InstalledHttpContract<...>`) | descriptor에 응답 모양 줄이 없다. 1103/16-01부터 필수 칸이다 | 짝 백엔드면 `responseEnvelope: "ENVELOPE_V1" as const`, 감싸지 않는 백엔드면 `"NONE" as const` |
| `: package version must be exact SemVer` | 버전 범위(`^1.2.0`)나 형식 오류 | `_CONTRACT_PACKAGE.version` |
### 라우트·context
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `Duplicate route registry key: ` | route ID 중복 | 계약 `routes`. 접두어를 붙인다 |
| `Duplicate route runtime contract key: ` | `routeRuntimeContracts` 중복 | 계약 `routeRuntimeContracts` |
| `Route () of feature is not under the route root of its context (): the router would answer NOT_FOUND.` | 라우트가 context 루트 밖 | 계약 `routes.*.path`, 또는 `CONTEXT_ROUTE_PATH` |
| `Route () of feature is not under the route root of its context (): context () takes that URL.` | 다른 context의 루트 아래 | 같은 곳 |
| `Route handle loaded by context is not a contract route of its features ().` | `context-routes.ts`의 handle이 계약에 없는 route ID | `src/features//context-routes.ts` |
### 문구·서버 상태
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `Duplicate message key: ` | 문구 키 중복 | `contracts/-message-catalog.ts`. 접두어를 붙인다 |
| `Duplicate invalidation topic: ` | topic 중복. 복사한 topic | 계약 `invalidation`. topic을 새로 만든다 |
| `Duplicate invalidation namespace: ` | namespace 중복 | `defineQueryNamespaceIdentity` 이름 |
| `Query invalidation topic is invalid.` | topic 형식이 `qinv.` + 26자가 아니다 | `defineQueryInvalidationTopic` 값 |
| `Orphan invalidation topic: ` | edge가 없는 topic | 계약 `invalidation.edges` |
| `Unregistered server-state profile: ` | 없는 profile | 쿼리 바인딩의 `profileId` |
| `commandMutationIdentity: is a GET; a mutation binds a write operation` | 뮤테이션 정책에 읽기 descriptor를 넘겼다 | 정책의 `commandMutationIdentity(...)` 인자를 쓰기 descriptor로 |
### 조립 기여
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `feature needs , which the host did not provide` | 템플릿이 만들지 않는 capability | `src/bootstrap/product-composition.ts`의 `capabilities`, 또는 `needs` |
| `feature adapter contribution installed an input for ` | 기여의 `featureId`와 만든 input의 `featureId`가 다르다 | `adapters/create--feature-input.ts` |
| `duplicate feature adapter contribution: ` | 두 기여가 같은 기능 ID | 복사한 기여 파일 |
| `Feature installed an input for ` | 지연 로드한 기능이 다른 기능의 input을 냈다 | `adapters/create--feature-input.ts` |
---
## 레지스트리 (check:registries)
모두 `Registry governance failed:` 다음 줄에 나온다.
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `FE-REG-ROUTE. duplicates path= from ` | 경로 중복 (`chunkId=`도 같은 꼴) | 계약 `routes` |
| `FE-REG-ROUTE..loadingSurface value does not match ` | 로딩 화면 이름이 케밥 표기가 아니다 | 계약 `routes.*.loadingSurface` |
| `FE-REG-ROUTE.. has unknown value ` | `access`·`errorSurface`가 정해진 값이 아니다 | 계약 `routes` |
| `FE-REG-ROUTE..paramsSchema references unknown FE-REG-SCHEMA.schemaId=` | 라우트 스키마 ID를 기능이 등록하지 않았다 (`searchSchema`도 같은 꼴) | 계약 스키마 메타 |
| `FE-REG-API. has no executable consumer for operationId=` | 계약의 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 descriptor를 지운다 |
| `missing registry source : ` | 레지스트리 source를 읽다가 오류가 났다. 계약 조립 실패면 ``가 `Installed contract contribution is not composable: `이고 ``이 위 `reason` 표의 값이다. 다른 오류가 `reason` 속성을 message와 따로 가지면 끝에 ` (reason: )`이 붙는다. 읽지 못한 레지스트리는 `removed` 증거를 요구하지 않는다 | ``이 가리키는 곳 |
| `breaking change missing evidence: ` | 행을 빼거나 바꿨는데 승인이 없다 | `update:registry-baseline` 또는 `config/contracts/registry-change-evidence.json` |
| `stale breaking evidence : no breaking change in the current diff has this changeId. ...` | 지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 |
| `registry baseline approval digest mismatch: approved= actual=` | 기준선 파일을 손으로 고쳤다 | `update:registry-baseline`으로 다시 찍는다 |
---
## 경계·lint·문구
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `check:architecture` 출력의 규칙 이름 (`feature-presentation-does-not-know-outbound-adapters` 등) | 금지된 import | 규칙 뜻은 `docs/architecture/layers.md`의 "Rules" 표가 정본 |
| `Screen words come from the message catalog: use message(key) (0929/08-02).` | 화면에 문자를 직접 썼다 | 문구 catalog에 키를 더하고 `message(key)` |
| `en-US catalog keys do not match ko-KR` (`I18n contract failed:` 다음) | 두 locale의 키가 다르다 | `contracts/-message-catalog.ts` |
| `en-US: interpolation parameters do not match` | `{name}` 자리가 locale마다 다르다 | 같은 파일 |
---
## 문서·접근성
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `artifacts/tests/a11y-manual/ has no record for route IDs: ` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 |
| `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 |
| `a11y.json not written:` 다음 `a11y: reads one resource () but has no failure-state record in artifacts/tests/a11y-data-state` (`test:a11y`, FE-GATE-009) | 라우트의 `paramsSchema`가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록을 남기지 않았다(1106/11-01). 그대로면 `a11y.json`이 그 라우트를 통과로 센다 | `tests/e2e/accessibility.spec.ts`의 기록 호출(`recordA11yDataState`). 기능 파일은 고치지 않는다 |
| `Manual accessibility evidence is incomplete:` 다음 `: ` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) |
| `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 |
| ` names paths that do not exist: ` (`verify:documentation`) | 문서가 없는 경로를 적었다 | 그 문서 |
---
## 릴리스 승인·공급망
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| `release admission refused for :` 다음 `contractPackages.: pins the placeholder identity create:feature writes; pin the published package's version, digest and revision` (FE-GATE-027) | 자리표시자 계약 신원으로 공개 대상 승인 | [03 문서 "자리표시자 계약 신원 교체"](../03-outside-feature-folder.md#자리표시자-계약-신원-교체) |
| `high-risk dependency missing review: add:@` (`generate:supply-chain`) | production 의존성을 더했는데 검토 기록이 없다 | `config/security/dependency-change-evidence.json` |
---
## 제거 드릴
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| ` removal failed:` 다음 `fixture-id-residue: residue: ` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features//`, `tests/features//`)에서 import하는 파일이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 |
| `No installed feature declares FEATURE_MODULE_ID ""` | `--feature=`에 없는 기능 ID | 명령 인자 |
| `feature scaffold failed:` 다음 `: ` (`test:feature-scaffold`) | 생성한 기능이 게이트 하나를 통과하지 못했다 | `scripts/create-feature.ts`의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 |