Files
clean-architecture-frontend…/docs/manual/reference/errors.md
T
DongHyeonka 5c2f8b875c docs(manual): 매뉴얼만으로 기능을 추가한 실험의 막힘 5건을 메운다 (1101/16-01)
문제: docs/manual(7c7ef32)만 보고 notice-feature(목록·상세·작성, GET 2 +
KEYED POST 1)를 만든 실험(b58d131, 합치지 않음)에서 매뉴얼이 답하지 않아
코드를 읽어야 했던 곳이 나왔다.

| 막힘 | 절 | 매뉴얼에 없던 것 |
|---|---|---|
| 1 | 01-3단계 | 백엔드 Envelope와 뼈대 problem details 중 무엇을 따르나 |
| 2 | 01-3단계 | V2 입력 칸(requestSource, pathSchema, pathParameterNames, maxEncodedSearchBytes, boundary) |
| 3 | 01-5단계 | routeId가 무엇에 쓰이고 쓰기에는 어느 route를 적나 |
| 4 | 01-6단계 | 상세 경로를 items/ 아래 두는 이유, a11y spec 치환 고치는 법 |
| 5 | 01-10단계 | 같은 멱등 키 재전송과 요청 본문을 테스트에서 보는 법 |
| 덧 | 02-4절, 01-2단계, patterns | 503 IDEMPOTENCY_UNAVAILABLE 판정, 길이 제한 위치, 검색 폼 예 |

고친 절과 근거(코드 위치):
- 01-3단계 "응답 모양": 뼈대·MSW·V3 실행기는 DTO와 problem details를 쓴다.
  V3는 본문을 벗기지 않고 검증한다(src/adapters/http/http-execution-v3.ts:1410,
  1633-1647; src/adapters/http/index.ts:41-48; backend-api-and-server-state-
  contract.md:161-173). MSW는 {data} 감싼 응답을 실패 시나리오로 둔다
  (tests/mocks/handlers/http-scenarios.ts:80-81, 143-150). 뼈대 problem 스키마는
  최상위 code다(scripts/create-feature.ts:542-550). 짝 백엔드는 모든 JSON을
  Envelope로 보낸다(backend docs/web/http-contract.md:16-33).
- 01-3단계 "V2 행의 입력 칸": 칸 표와 공지 예 두 행. 근거
  src/contracts/api-operations.ts:9,25-27,112-125,142-190,
  src/contracts/schema-registry.ts:6-11, config/contracts/registry-governance.json:220
  (boundary는 허용값만 검사), tests/unit/http-operation-v2-v3-parity.test.ts:39-49,91,
  src/adapters/http/request-builder.ts:129-135(V2만 읽음),
  src/contracts/external-contract-runtime.ts:33,
  src/adapters/http/http-contract-bridge.ts:225-231(V3 고정 상한 8,192).
- 01-5단계 routeId: 실행기에 넘겨 관측 기록의 route_id로만 쓴다
  (src/adapters/http/feature-http-binding.ts:272-273,
  src/adapters/http/http-execution-v3.ts:248-254,653-655,
  src/bootstrap/runtime-adapters.ts:249-293). 기준은 "요청을 보내는 화면".
  참조 기능 생성은 LIST를 적었다(reference-http-gateway.ts:32-34).
- 01-6단계: items/ 이유(reference-feature-contract.ts:36-37, React Router
  정적 우선), a11y spec 치환 줄(tests/e2e/accessibility.spec.ts:26-29,36-43),
  파라미터 해석 실패 시 잘못된 경로 화면(src/presentation/routes/app-router.tsx:371).
  드릴 잔여물 검사는 기능 ID·폴더 이름만 찾는다(scripts/test-sample-removal.ts:
  114-117,383-392). URL 함수가 codec을 넘겨야 한다는 줄도 더했다
  (src/presentation/routes/route-codecs.ts:36,69-87; 생성 판
  scripts/create-feature.ts:934-938은 넘기지 않음).
- 03 "기능을 지울 때"·C절, 01-11단계: a11y spec 치환 줄을 손으로 지운다.
- 01-10단계, patterns "테스트": msw request:start로 요청을 모으는 예
  (실험 tests/features/notice-feature/notice-pages.test.tsx, msw 2.15
  node_modules/msw/lib/core/experimental/frames/http-frame.d.ts:58,
  생성 판 setupServer scripts/create-feature.ts:1147-1149).
- 02-4절 503: V3는 problem 스키마 실패면 쓰기를 MAYBE_APPLIED로 두고
  (http-execution-v3.ts:1633-1647), 통과하면 기능 classifyProblem이 정한다
  (src/adapters/http/http-effect-certainty.ts:99-131; 참조 기능
  reference-feature-contract-contribution.ts:49-70은 503을 MAYBE_APPLIED).
  V2 IDEMPOTENCY_REFUSALS에 503이 없어 effect가 비고
  (src/adapters/http/client.ts:1035-1038,1109-1135) 조정자가 MAYBE_APPLIED로
  본다(src/presentation/adapters/query/application-query.ts:824-834). 재전송은
  같은 키, 새 저장은 새 키(같은 파일 583-589, 636-669). 판정: 백엔드 행동
  (http-contract.md:94 "같은 키로 나중에 다시")과 맞는다. 화면 문구만 다르다.
- 01-2단계: 길이 제한은 경계 검증. 참조 기능도 스키마·폼에만 둔다
  (reference-schemas.ts:66, reference-resource-form.ts:9).
- patterns "URL 검색값을 바꾸는 폼": 짧은 예(SearchField, CollectionPage
  toolbar, buildRouteUrl search).
- errors.md: V2 입력 칸 실패 메시지 3개와 Unregistered route codec.

남긴 것:
- 응답 모양 제한: 지금 생성한 기능은 짝 백엔드의 Envelope 응답을 읽지
  못한다. 매뉴얼에는 제한과 선택지 둘(백엔드가 DTO를 보냄 / 프론트 V3가
  Envelope를 벗김)만 적었다. 결정은 없다. CHANGELOG·리뷰 기록은 이 커밋
  범위 밖이다.
- 경로 파라미터와 본문을 함께 받는 operation(PUT 등)의 V2/V3 일치 규칙이
  없다는 사실만 적었다.
- 예시 코드는 실험 브랜치의 notice 기능에서 옮겼다. 이 저장소에서 다시
  돌려 보지 않았다(실험 커밋 기록상 기능 테스트 21개 통과).

검증:
- node scripts/generate-product-feature-index.ts &&
  node scripts/verify-documentation-readiness.ts: PASS_SCOPED,
  documentReferences의 docs/manual 8개 파일 missing 0
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
  tests/unit/documentation-readiness.test.ts: 2 파일 16개 통과
- 새로 적은 실패 메시지·식별자: src·scripts·tests에서 모두 찾음.
  request:start는 msw 타입에서 확인
2026-11-03 08:01:49 +09:00

17 KiB

실패 메시지와 고칠 파일

기능을 만들 때 흔히 보는 실패 메시지다. 메시지는 코드의 문자열을 그대로 옮겼다. <...>는 실제 값이 들어가는 자리다.

찾는 법: 메시지 앞부분으로 이 문서를 검색한다. 없으면 git grep '<메시지 앞부분>' -- src scripts로 코드를 찾는다. 코드가 정본이다.

메시지가 어느 단계에서 나오는지:

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

<base>는 기능 ID에서 끝의 -feature를 뗀 것이다.


생성 명령 (create:feature)

모두 create:feature: 뒤에 나온다. 종료 코드는 1이다(인자 오류는 2).

메시지 원인 고칠 곳
feature id "<id>" must be kebab-case (lower-case words joined by single hyphens), at most 40 characters ID 형식 명령 인자
context id "<context>" must be kebab-case (lower-case words joined by single hyphens), at most 64 characters --context 형식 명령 인자
feature id <id> is already a feature or context 같은 ID가 있다 다른 ID
feature id <id> would prefix its ids with "<base>", which <other> already uses 접두어가 기존 기능과 같다 다른 ID
context <context> already exists; pass --context <context> to add the feature to it 새로 만들 context가 이미 있다 --context <context>를 준다
context id <context> is a feature id context ID가 기능 ID와 같다 다른 --context
src/contexts has a <context> directory without a context declaration 선언 없는 context 폴더 src/contexts/<context>/context-module.ts를 만들거나 폴더를 지운다
another context already owns the route root <root>/* 같은 라우트 루트를 다른 context가 가진다 다른 ID, 또는 그 context에 --context로 넣는다
a new context needs exactly one deployable app (declared: <apps>); pass --context <an existing context> 앱이 여럿이라 새 context의 소속을 정할 수 없다 --context
route <ROUTE_ID> (<path>, <chunkId>) collides with installed route <ROUTE_ID> (<path>, <chunkId>) route ID·경로·chunk가 겹친다 다른 ID
message keys already exist: <keys> 문구 키가 겹친다 다른 ID
generated topic <topic> is already installed; run the command again 무작위 topic이 우연히 겹쳤다 명령을 다시 돌린다
contract package <packageId>@<version> is not a pinned identity: <reason> 패키지 신원 형식. <reason> 예: <id>: package version must be exact SemVer, <id>: package digest, <id>: package sourceRevision, <id>: packageId --package, --digest, --revision
--package, --digest and --revision go together. ... 셋 중 일부만 줬다 셋을 함께 준다
--package must be @scope/name@<exact version>. ... 버전 없는 패키지 이름 @scope/name@1.2.3 꼴
refusing to overwrite: <paths> 쓸 파일이나 기능 폴더가 이미 있다 그 경로를 확인하고 지우거나 다른 ID
the feature index generator rejected the feature, nothing was kept: 생성기가 거부했다. 만든 파일은 모두 지웠다 뒤따르는 생성기 메시지(아래 절)

생성기 (generate:feature-index)

메시지 원인 고칠 곳
Feature <id> belongs to undeclared context <context> context 선언이 없거나 FEATURE_CONTEXT_ID 오타 src/contexts/<context>/context-module.ts, 또는 src/features/<id>/feature-module.ts
Context <context> belongs to undeclared app <app> CONTEXT_APP_ID 오타 src/contexts/<context>/context-module.ts
<file> must export a literal <NAME> 헤더를 상수 참조나 식으로 썼다. 생성기는 글자로 읽는다 그 파일. export const <NAME> = "<값>"; 꼴
<file> must export a positive integer <NAME> 예산 값이 정수 리터럴이 아니다 그 파일
src/features/<dir> has no feature-module.ts; add one or mark the directory with NOT_INSTALLED 기능 폴더에 선언 파일이 없다 feature-module.ts를 만들거나 NOT_INSTALLED 파일을 둔다
Duplicate generated feature ids: <id> 두 폴더가 같은 FEATURE_MODULE_ID 한쪽 feature-module.ts
Duplicate context id: <id> 두 폴더가 같은 CONTEXT_MODULE_ID 한쪽 context-module.ts
Context <context> feature cardinality <n> exceeds budget <max> context의 기능 수가 예산을 넘었다 CONTEXT_MAX_FEATURES, 또는 새 context
App <app> context cardinality <n> exceeds budget <max> 앱의 context 수가 예산을 넘었다 src/apps/<app>/app-module.ts의 APP_MAX_CONTEXTS

조립·모듈 로드

테스트, 빌드, 앱 부팅 어디서든 나온다. 한 기능의 실수가 거의 모든 게이트를 같이 실패시킨다. 첫 메시지를 본다.

인증 프로필

메시지 원인 고칠 곳
REST security profiles are incoherent for <operationId>: unknown authProfileId <id>. 없는 인증 프로필 contracts/<base>-api-contract.ts의 authProfileId. 제품 프로필이면 src/contracts/product-contracts.ts
REST security profiles are incoherent for <operationId>: unknown csrfProfileId <id>. 없는 CSRF 프로필. 템플릿에는 NO_CSRF_BEARER뿐 contracts/<base>-api-contract.ts의 csrfProfileId
REST security profiles are incoherent for <operationId>: auth "none" needs an ANONYMOUS profile, <id> is <transport>. V2 auth: "none"인데 인증 프로필을 썼다 V2 auth 또는 authProfileId
REST security profiles are incoherent for <operationId>: auth "external-session" cannot use the ANONYMOUS profile <id>. 로그인 API에 ANONYMOUS V2 auth 또는 authProfileId
Product REST auth profile <id> reuses a template profile id. 제품 프로필 ID가 템플릿 것과 같다 src/contracts/product-contracts.ts

계약·스키마·mapper

메시지 원인 고칠 곳
Invalid or duplicate schema definition: <schemaId> 스키마 ID 중복 또는 메타 형식 contracts/<base>-api-contract.ts의 schemas. 접두어를 붙인다
Invalid or duplicate runtime schema codec: <schemaId> 런타임 codec ID 중복 contracts/<base>-schemas.ts
Invalid or duplicate boundary mapper: <mapperId> mapper ID 중복 또는 형식 contracts/<base>-mapper.ts
Duplicate API operation: <operationId> V2 operation ID 중복 contracts/<base>-api-contract.ts
REST path codec does not match its template: <operationId> V2 pathParameterNames가 path의 {이름}과 다르다 contracts/<base>-api-contract.ts (01 문서 3단계 "V2 행의 입력 칸")
Invalid REST operation contract: <operationId> V2 행 형식. 예: 빈 pathSchema, maxEncodedSearchBytes가 0~32,768 밖 같은 곳
Unresolved API schema binding: <operationId> V2 pathSchema·requestSchema·responseSchema가 등록되지 않은 스키마 같은 파일의 schemas, contracts/<base>-schemas.ts의 codec
Unregistered route codec: <codecId> URL 함수가 기능 codec을 buildRouteUrl에 넘기지 않았다 presentation/<base>-routes.ts
contract package <packageId> is declared, but no loaded contribution pins it 계약 contractPackages에 적은 패키지를 계약 기여가 쓰지 않는다 contracts/<base>-contract-contribution.ts의 source
<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages 계약 기여의 신원과 계약 선언의 신원이 다르다 둘 다 <BASE>_CONTRACT_PACKAGE 하나를 쓰게 한다
contract package <packageId> is declared with conflicting identities 두 기능이 같은 패키지를 다른 버전·digest로 선언했다 두 기능의 <BASE>_CONTRACT_PACKAGE를 맞춘다

계약 조립 실패는 메시지가 Installed contract contribution is not composable 하나다. 원인은 오류 객체(ContractContributionError)의 reason 속성에 있다. 메시지만 보이면 reason을 출력해 본다.

reason 원인 고칠 곳
<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE 참조 기능 전용 출처를 다른 기능이 썼다 contracts/<base>-contract-contribution.ts의 source를 EXTERNAL_PACKAGE로
duplicate operation: <operationId> 두 기여가 같은 operation ID 접두어를 붙인다
duplicate contributionId: <id> 두 기여가 같은 contributionId contracts/<base>-contract-contribution.ts
<id>/<operationId>: unknown authProfileId <profile> V3 frontend.authProfileId가 없는 프로필 V3 frontend.authProfileId
<id>/<operationId>: retry budget contradicts NEVER retry semantics NEVER인데 retryBudget가 0이 아니다 V3 frontend.retryBudget
<id>/<operationId>: KEYED commands require a recovery descriptor KEYED인데 commandRecovery가 없다 V3 commandRecovery
<id>/<operationId>: command operations require a command effect descriptor 쓰기에 commandEffect가 없다 V3 commandEffect
<id>/<operationId>: read operations carry no command descriptors GET에 commandEffect·commandRecovery를 적었다 둘 다 null
<id>: package version must be exact SemVer 버전 범위(^1.2.0)나 형식 오류 <BASE>_CONTRACT_PACKAGE.version

라우트·context

메시지 원인 고칠 곳
Duplicate route registry key: <ROUTE_ID> route ID 중복 계약 routes. 접두어를 붙인다
Duplicate route runtime contract key: <ROUTE_ID> routeRuntimeContracts 중복 계약 routeRuntimeContracts
Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): the router would answer NOT_FOUND. 라우트가 context 루트 밖 계약 routes.*.path, 또는 CONTEXT_ROUTE_PATH
Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): context <other> (<root>) takes that URL. 다른 context의 루트 아래 같은 곳
Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (<ids>). context-routes.ts의 handle이 계약에 없는 route ID src/features/<id>/context-routes.ts

문구·서버 상태

메시지 원인 고칠 곳
Duplicate <locale> message key: <key> 문구 키 중복 contracts/<base>-message-catalog.ts. 접두어를 붙인다
Duplicate invalidation topic: <topic> topic 중복. 복사한 topic 계약 invalidation. topic을 새로 만든다
Duplicate invalidation namespace: <key> namespace 중복 defineQueryNamespaceIdentity 이름
Query invalidation topic is invalid. topic 형식이 qinv. + 26자가 아니다 defineQueryInvalidationTopic 값
Orphan invalidation topic: <topic> edge가 없는 topic 계약 invalidation.edges
Unregistered server-state profile: <profileId> 없는 profile 쿼리 바인딩의 profileId

조립 기여

메시지 원인 고칠 곳
feature <id> needs <capability>, which the host did not provide 템플릿이 만들지 않는 capability src/bootstrap/product-composition.ts의 capabilities, 또는 needs
feature adapter contribution <id> installed an input for <other> 기여의 featureId와 만든 input의 featureId가 다르다 adapters/create-<base>-feature-input.ts
duplicate feature adapter contribution: <id> 두 기여가 같은 기능 ID 복사한 기여 파일
Feature <id> installed an input for <other> 지연 로드한 기능이 다른 기능의 input을 냈다 adapters/create-<base>-feature-input.ts

레지스트리 (check:registries)

모두 Registry governance failed: 다음 줄에 나온다.

메시지 원인 고칠 곳
FE-REG-ROUTE.<ROUTE_ID> duplicates path=<path> from <ROUTE_ID> 경로 중복 (chunkId=도 같은 꼴) 계약 routes
FE-REG-ROUTE.<ROUTE_ID>.loadingSurface value <value> does not match <pattern> 로딩 화면 이름이 케밥 표기가 아니다 계약 routes.*.loadingSurface
FE-REG-ROUTE.<ROUTE_ID>.<field> has unknown value <value> access·errorSurface가 정해진 값이 아니다 계약 routes
FE-REG-ROUTE.<ROUTE_ID>.paramsSchema references unknown FE-REG-SCHEMA.schemaId=<id> 라우트 스키마 ID를 기능이 등록하지 않았다 (searchSchema도 같은 꼴) 계약 스키마 메타
FE-REG-API.<operationId> has no executable consumer for operationId=<operationId> V2 operation을 기능 adapters/·application/에서 쓰지 않는다 쓰지 않으면 V2 행을 지운다
breaking change missing evidence: <changeId> 행을 빼거나 바꿨는데 승인이 없다 update:registry-baseline 또는 config/contracts/registry-change-evidence.json
stale breaking evidence <changeId>: no breaking change in the current diff has this changeId. ... 지금 diff와 맞지 않는 증거 행 그 행을 지운다
registry baseline approval digest mismatch: approved=<digest> actual=<digest> 기준선 파일을 손으로 고쳤다 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/<base>-message-catalog.ts
en-US:<key> interpolation parameters do not match {name} 자리가 locale마다 다르다 같은 파일

문서·접근성

메시지 원인 고칠 곳
artifacts/tests/a11y-manual/ has no record for route IDs: <ids> (verify:documentation) 라우트의 a11y 기록 파일이 없다 기존 pending 기록을 복사해 제목과 Route ID를 바꾼다
Manual accessibility record format is invalid: 다음 artifacts/tests/a11y-manual/<ROUTE_ID>.md: missing record (FE-GATE-009) 같은 원인 같은 곳
Manual accessibility evidence is incomplete: 다음 <ROUTE_ID>: <failures> (FE-GATE-028) 서명하지 않은 기록 03 문서
release IDs do not match (FE-GATE-028) 라우트마다 다른 릴리스로 검토했다 같은 릴리스 후보로 다시 검토한다
<doc> names paths that do not exist: <paths> (verify:documentation) 문서가 없는 경로를 적었다 그 문서

릴리스 승인·공급망

메시지 원인 고칠 곳
release admission refused for <target>: 다음 contractPackages.<packageId>: pins the placeholder identity create:feature writes; pin the published package's version, digest and revision (FE-GATE-027) 자리표시자 계약 신원으로 공개 대상 승인 03 문서 "자리표시자 계약 신원 교체"
high-risk dependency missing review: add:<name>@<version> (generate:supply-chain) production 의존성을 더했는데 검토 기록이 없다 config/security/dependency-change-evidence.json

제거 드릴

메시지 원인 고칠 곳
<id> removal failed: 다음 fixture-id-residue: residue: <files> (test:sample-removal) 기능을 지운 뒤에도 src·tests에 기능 ID를 담은 파일이 남았다 그 파일을 기능 폴더 안으로 옮기거나, 기능 ID를 담지 않게 한다
No installed feature declares FEATURE_MODULE_ID "<id>" --feature=에 없는 기능 ID 명령 인자
feature scaffold failed: 다음 <check>: <failure> (test:feature-scaffold) 생성한 기능이 게이트 하나를 통과하지 못했다 scripts/create-feature.ts의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다