TML-3071: error-reference page for all 221 codes + CI completeness check

[wmadden-electric]

Linked issue

Refs TML-3071. Error-consolidation follow-through of TML-3067 / PR #1016 (ADR 239): shipped error messages already print docs.prisma.io/.../error-reference#<CODE> URLs; this makes the page real and provably complete before RC (Jul 31).

At a glance

### CONTRACT.MARKER_MISSING

No contract marker (database signature) is found in the database at all. Surfaces from
verify-style CLI operations, and as a runtime warning during startup marker verification.
Fix path: `prisma-next db sign`.

One such entry now exists for every one of the 221 published codes, and CI fails any PR that adds a code without one:

$ pnpm check:error-reference
error-reference lists all 221 known codes.

Decision

1. The canonical error-reference page lives in this repo, at docs/reference/error-reference.md — matching the hosted URL slug. It opens with how to recognize errors programmatically (isStructuredError + code), the reserved exit codes, a pointer to the ADR 239 crosswalk, and a namespace overview table, then lists all 221 codes grouped by namespace with ### headings (so each code is an anchor). Every entry says what condition produces the error, during which command or API, and its notable meta keys. Three factory-declared codes with no production call site are documented as "Reserved".
2. The completeness requirement runs per-PR in this repo's CI: pnpm check:error-reference (wired into the Lint job) runs scripts/list-error-codes.mjs --verify against the page and fails listing any code in production source the page omits.

Reviewer notes

• Placement is the one judgment call. The ticket allowed the page to live in the docs-site repo with a scheduled fallback check. Keeping the canonical source here makes the completeness requirement a hard per-PR CI failure instead of a soft scheduled one; the docs site ingests this file at publish time and can re-run the same script against a prisma-next checkout via the existing --root flag.
• Entry accuracy over eloquence: every entry was drafted from the defining file(s) and throw sites (not from memory), including per-site meta differences (e.g. RUNTIME.DECODE_FAILED's three carriers) and severity nuances (LINT.SELECT_STAR warns on the AST path, errors on raw SQL; CONTRACT.MARKER_MISSING is a hard failure from verify commands but a warning at runtime startup).
• No script changes: list-error-codes.mjs and its tests already existed (from TML-3067: all error codes become dotted NAMESPACE.SUBCODE (ADR 239) #1016); this PR only adds the page, the check:error-reference script entry, the CI step, and two doc links.

Testing performed

• pnpm check:error-reference — lists all 221 known codes.
• pnpm test:scripts — 206/206 (the one initial red was a workspace-link install-state issue from TML-3072: fold ref-paired snapshots into the content-addressed store #1024's new test, fixed by pnpm install, no code change).
• pnpm lint:workflows, pnpm lint:docs — clean.

Follow-ups

• Docs-site ingestion of this page (and its --verify --root check in that repo's build) happens in the docs repo; the next → v8 URL-segment flip is the one-token DOCS_ERRORS_VERSION change at RC.
• Future plane sweeps (adapters, extensions) add codes; the CI check forces their entries to land in the same PR.

Alternatives considered

• Page lives only in the docs-site repo — rejected; prisma-next CI could not then fail a PR that adds an undocumented code, and the ticket's fallback (scheduled check) surfaces omissions days later instead of at review time.
• Generating the page fully from source at build time — rejected; the enumerator can extract codes but not meaning. The prose is the deliverable; the generator's --verify mode keeps the hand-written page honest instead.

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated.
• The PR title is in TML-NNNN: <sentence-case title> form.
• The Skill update section: no skill changes — docs page + CI check only; no examples/ or packages/3-extensions/ files touched, so no upgrade-recipe entry is required.

[coderabbitai]

Warning

Review limit reached

@wmadden-electric, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 13 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: af0db49a-9a10-41b9-a0aa-a64ebff826d9

📥 Commits

Reviewing files that changed from the base of the PR and between 180a06d and 9c5b0e0.

📒 Files selected for processing (5)

• .github/workflows/ci.yml
• docs/Error Handling.md
• docs/README.md
• docs/reference/error-reference.md
• package.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-3071-docs-error-reference

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

size-limit report 📦

Path	Size
postgres / no-emit	163.12 KB (0%)
postgres / emit	145.29 KB (0%)
mongo / no-emit	100.15 KB (0%)
mongo / emit	89.86 KB (0%)
cf-worker / no-emit	188.4 KB (0%)
cf-worker / emit	168.61 KB (0%)

[pkg-pr-new]

Open in StackBlitz

@prisma-next/extension-author-tools

npm i https://pkg.pr.new/@prisma-next/extension-author-tools@1027

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/@prisma-next/mongo-runtime@1027

@prisma-next/family-mongo

npm i https://pkg.pr.new/@prisma-next/family-mongo@1027

@prisma-next/sql-runtime

npm i https://pkg.pr.new/@prisma-next/sql-runtime@1027

@prisma-next/family-sql

npm i https://pkg.pr.new/@prisma-next/family-sql@1027

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/@prisma-next/extension-arktype-json@1027

@prisma-next/middleware-cache

npm i https://pkg.pr.new/@prisma-next/middleware-cache@1027

@prisma-next/mongo

npm i https://pkg.pr.new/@prisma-next/mongo@1027

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/@prisma-next/extension-paradedb@1027

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/@prisma-next/extension-pgvector@1027

@prisma-next/extension-postgis

npm i https://pkg.pr.new/@prisma-next/extension-postgis@1027

@prisma-next/postgres

npm i https://pkg.pr.new/@prisma-next/postgres@1027

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/@prisma-next/sql-orm-client@1027

@prisma-next/sqlite

npm i https://pkg.pr.new/@prisma-next/sqlite@1027

@prisma-next/extension-supabase

npm i https://pkg.pr.new/@prisma-next/extension-supabase@1027

@prisma-next/target-mongo

npm i https://pkg.pr.new/@prisma-next/target-mongo@1027

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/@prisma-next/adapter-mongo@1027

@prisma-next/driver-mongo

npm i https://pkg.pr.new/@prisma-next/driver-mongo@1027

@prisma-next/contract

npm i https://pkg.pr.new/@prisma-next/contract@1027

@prisma-next/utils

npm i https://pkg.pr.new/@prisma-next/utils@1027

@prisma-next/config

npm i https://pkg.pr.new/@prisma-next/config@1027

@prisma-next/errors

npm i https://pkg.pr.new/@prisma-next/errors@1027

@prisma-next/framework-components

npm i https://pkg.pr.new/@prisma-next/framework-components@1027

@prisma-next/operations

npm i https://pkg.pr.new/@prisma-next/operations@1027

@prisma-next/ts-render

npm i https://pkg.pr.new/@prisma-next/ts-render@1027

@prisma-next/contract-authoring

npm i https://pkg.pr.new/@prisma-next/contract-authoring@1027

@prisma-next/ids

npm i https://pkg.pr.new/@prisma-next/ids@1027

@prisma-next/psl-parser

npm i https://pkg.pr.new/@prisma-next/psl-parser@1027

@prisma-next/psl-printer

npm i https://pkg.pr.new/@prisma-next/psl-printer@1027

@prisma-next/cli

npm i https://pkg.pr.new/@prisma-next/cli@1027

@prisma-next/cli-telemetry

npm i https://pkg.pr.new/@prisma-next/cli-telemetry@1027

@prisma-next/config-loader

npm i https://pkg.pr.new/@prisma-next/config-loader@1027

@prisma-next/emitter

npm i https://pkg.pr.new/@prisma-next/emitter@1027

@prisma-next/language-server

npm i https://pkg.pr.new/@prisma-next/language-server@1027

@prisma-next/migration-tools

npm i https://pkg.pr.new/@prisma-next/migration-tools@1027

prisma-next

npm i https://pkg.pr.new/prisma-next@1027

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/@prisma-next/vite-plugin-contract-emit@1027

@prisma-next/mongo-codec

npm i https://pkg.pr.new/@prisma-next/mongo-codec@1027

@prisma-next/mongo-contract

npm i https://pkg.pr.new/@prisma-next/mongo-contract@1027

@prisma-next/mongo-value

npm i https://pkg.pr.new/@prisma-next/mongo-value@1027

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/@prisma-next/mongo-contract-psl@1027

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/@prisma-next/mongo-contract-ts@1027

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/@prisma-next/mongo-emitter@1027

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/@prisma-next/mongo-schema-ir@1027

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/@prisma-next/mongo-query-ast@1027

@prisma-next/mongo-orm

npm i https://pkg.pr.new/@prisma-next/mongo-orm@1027

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/@prisma-next/mongo-query-builder@1027

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/@prisma-next/mongo-lowering@1027

@prisma-next/mongo-wire

npm i https://pkg.pr.new/@prisma-next/mongo-wire@1027

@prisma-next/sql-contract

npm i https://pkg.pr.new/@prisma-next/sql-contract@1027

@prisma-next/sql-errors

npm i https://pkg.pr.new/@prisma-next/sql-errors@1027

@prisma-next/sql-operations

npm i https://pkg.pr.new/@prisma-next/sql-operations@1027

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/@prisma-next/sql-schema-ir@1027

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/@prisma-next/sql-contract-psl@1027

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/@prisma-next/sql-contract-ts@1027

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/@prisma-next/sql-contract-emitter@1027

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/@prisma-next/sql-lane-query-builder@1027

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/@prisma-next/sql-relational-core@1027

@prisma-next/sql-builder

npm i https://pkg.pr.new/@prisma-next/sql-builder@1027

@prisma-next/target-postgres

npm i https://pkg.pr.new/@prisma-next/target-postgres@1027

@prisma-next/target-sqlite

npm i https://pkg.pr.new/@prisma-next/target-sqlite@1027

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/@prisma-next/adapter-postgres@1027

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/@prisma-next/adapter-sqlite@1027

@prisma-next/driver-postgres

npm i https://pkg.pr.new/@prisma-next/driver-postgres@1027

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/@prisma-next/driver-sqlite@1027

commit: 9c5b0e0