Repository navigation
e87bb2cd-followup: KB docs resolve returns clean 404 for unresolvable path-shaped refs - #325
Merged
Merged
Conversation
…oc refs normalizePathAlias threw a plain Error for path-shaped refs that do not end in .md; that error escaped resolveReference, bypassed the LookupError handling in every caller, and surfaced as a 500 on /docs/resolve for any ref containing '/' matching no document. Throw LookupError instead so all callers map it to their existing not-found paths (404 JSON on the resolve endpoint, NotFound elsewhere, registry violations during build). Valid .md path aliases are unaffected. Tests: unknown path-shaped ref -> LookupError (unit) and 404 (API), unknown dotted ref -> 404 unchanged, valid doc and valid path alias -> 200/resolved.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to task e87bb2cd. Live prod bug verified 2026-11-04 ~18:37Z:
kb show "00-start-here/no-such-doc"(ref contains/, matches no document) returned 500 Internal server error instead of the clean 404 that non-path refs get.Root cause
normalizePathAlias(backend/src/docs/docRegistry.ts:417-422on origin/main) didif (!path.endsWith('.md')) throw new Error(alias). That plainErroris not aLookupError, soresolveReferencelet it escape (docRegistry.ts:273-274) andresolveDoc'sLookupError→404 mapping (contentApi.ts:619-631) never caught it — the catch-all turned it into a 500.Fix (minimal)
normalizePathAliasnow throwsLookupError(Document reference not found: ${alias})— the same error type already used byresolveReferencefor unresolvable refs. Verified every caller ofresolveReference/normalizePathAliashandlesLookupError(or any error) safely:contentApi.ts/docs/resolve→ 404 JSON (line 627); other doc routes →NotFound(lines 565, 771, 835, 847)contentApi.ts:703(code-view sop) and:967(move parent) → bare catch → violation / 400taskChecklist.ts:122→ null;:180→ 404docRegistry.tsregistry build (lines 158-162, 184-188) → bare catch → violation/skip (unchanged behavior)canResolve(docRegistry.ts:440) → bare catch → falseValid
.mdpath aliases are unaffected: the throw only fires when the path does not end in.md; resolution viaregistry.byPathafterwards is unchanged.Tests
backend/tests/docs-registry.test.ts: unknown path-shaped ref (00-start-here/no-such-doc) →LookupErrorwithDocument reference not found: ...message (not a plain Error); unknown.mdpath →LookupError; valid path ref still resolves.backend/tests/docs-content-api.test.ts:GET /docs/resolve— path-shaped unknown ref → 404Document reference not found(not 500); unknown dotted ref → 404 (unchanged); valid doc ref → 200; valid path alias (accounts/sops/reset-password.md) → 200 resolving tocontent/accounts/sops/reset-password.md.Both touched test files pass locally; no other suites run.
Known gap (out of scope)
The Python reference implementation
tools/content_tools/content_tools/doc_registry.py:293-299has the same structure (_normalize_path_aliasraisesValueError, uncaught inresolve_referenceat line 153). Not touched here — this PR fixes the TS backend that serves prod.