docs: add the canonical error-reference registry and completeness check

[wmadden-electric]

Replicates prisma/prisma's error-reference pattern in this repo so the docs site can aggregate the unified CLI's structured errors — and removes the legacy error layer that made a complete registry impossible. Companion web PR follows (it consumes this registry and must merge after this).

The registry and its check

• docs/reference/error-reference.md — the canonical registry: every NAMESPACE.SUBCODE code in production source across 11 namespaces (AUTH, BRANCH, BUCKET, CLI, FEEDBACK, GIT, INIT, POSTGRES, PROJECT, SERVICE, SKILLS), each entry stating the condition that raises it, the command or boundary, the fix where the source carries one, and its meta fields. Warn-severity diagnostics that ride successful runs are labeled as such.
• scripts/list-error-codes.mjs — enumerates codes from git-tracked production source (mirror of prisma/prisma's scanner; closed namespace list; json / markdown-skeleton / --verify modes; --root lets the docs repo run it against a checkout). It skips tracked-but-deleted files, so a branch mid-delete reports instead of crashing.
• pnpm check:error-reference — wired into pr-quality.yml as a required-check job: a new code cannot ship undocumented.
• docsBaseUrl set on platformCommandFamily and skillsCommandFamily, so emitted errors now carry docsUrl = https://www.prisma.io/docs/cli/error-reference/<CODE> (the docs site redirects that path form to the #<CODE> anchor, same convention the ORM family uses). CLI_DOCS_URL also moves from the docs root to /docs/cli, which now exists.

Structured errors at origin: the legacy layer is gone

A registry is only as honest as the codes it can see, and a scanner reads string literals. The CLI had a second error system underneath — a legacy CliError with flat codes (PROJECT_AMBIGUOUS, DATABASE_API_ERROR) that per-domain boundary mappers rewrote into dotted codes on the way out. Two of those rewrites built codes by concatenation:

• fromLegacyCliError prefixed SERVICE. onto whatever code it was handed. A --project that matched nothing became SERVICE.PROJECT_AMBIGUOUS through a service command and PROJECT.AMBIGUOUS through a project command — two codes for one condition, and the first appears nowhere in source, so neither the scanner nor the registry nor a caller could know it exists.
• The API mappers used a server-supplied code as the error code, so a 403 surfaced as PROJECT.forbidden — a lowercase code invented by a remote service. A test had pinned that shape.

Both are deleted, along with the whole legacy layer:

• Every raise site now constructs CliStructuredError with its registered code directly. packages/cli/src/errors.ts (the CliError class, usageError, authRequiredError, …), next-actions.ts's parallel NextAction type, and the five mapper modules (commands/{project,branch,bucket,postgres,git}/errors.ts) are gone or reduced to real factories.
• The try { … } catch { const mapped = map…(error) } wrapper in every command handler is gone; structured errors settle themselves.
• A failed Management API call raises the domain's registered *.API_ERROR with the API's own code and status in meta.apiCode / meta.status, where they are data a caller can read.
• A 401/403 from an API call no longer mints an *.AUTH_REQUIRED code that never existed in source; it is the domain's API error with meta.status and an auth login next action.
• The legacy free-text fix is now the first user-choice next action, and nextSteps command strings are run-command actions — the rendering the mappers produced, built at the raise site. Install URLs are open-url actions rather than commands.

docs/product/error-conventions.md loses its pre-dotted "MVP Error Codes" list and its stale JSON envelope example, and states the two rules this PR enforces: assign the code at origin, and treat a server's code as data.

Deliberate remaining duplication

SERVICE.PROJECT_NOT_FOUND survives as its own code: it is authored at a raise site, for the services API refusing a project that had already resolved. That is a different moment from a --project reference matching nothing, which is now PROJECT.NOT_FOUND from every command. Worth a look if you would rather collapse the two.

Verification

• pnpm check:error-reference — registry and source agree exactly, in both directions
• pnpm typecheck, pnpm check:grammar, biome clean on touched files
• Full @prisma/cli test suite green; the tests that pinned PROJECT.forbidden, GIT.AUTH_REQUIRED, PROJECT.AUTH_REQUIRED, and SERVICE.PROJECT_NOT_FOUND for an unmatched --project were pinning the invented codes and now pin the registered ones

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 19 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7d10dde9-9117-45e5-b039-010f2b178eac

📥 Commits

Reviewing files that changed from the base of the PR and between 5468362 and 1d2e5c7.

📒 Files selected for processing (77)

• .github/workflows/pr-quality.yml
• docs/product/error-conventions.md
• docs/reference/error-reference.md
• package.json
• packages/cli/src/cli-name.ts
• packages/cli/src/cli.ts
• packages/cli/src/commands/branch/errors.ts
• packages/cli/src/commands/branch/list.ts
• packages/cli/src/commands/bucket/context.ts
• packages/cli/src/commands/bucket/create.ts
• packages/cli/src/commands/bucket/delete.ts
• packages/cli/src/commands/bucket/errors.ts
• packages/cli/src/commands/bucket/key-create.ts
• packages/cli/src/commands/bucket/key-delete.ts
• packages/cli/src/commands/bucket/key-list.ts
• packages/cli/src/commands/bucket/list.ts
• packages/cli/src/commands/git/connect.ts
• packages/cli/src/commands/git/disconnect.ts
• packages/cli/src/commands/git/errors.ts
• packages/cli/src/commands/postgres/backup-list.ts
• packages/cli/src/commands/postgres/backup-restore.ts
• packages/cli/src/commands/postgres/connection-create.ts
• packages/cli/src/commands/postgres/connection-delete.ts
• packages/cli/src/commands/postgres/connection-list.ts
• packages/cli/src/commands/postgres/connection-rotate.ts
• packages/cli/src/commands/postgres/context.ts
• packages/cli/src/commands/postgres/create.ts
• packages/cli/src/commands/postgres/delete.ts
• packages/cli/src/commands/postgres/errors.ts
• packages/cli/src/commands/postgres/list.ts
• packages/cli/src/commands/postgres/show.ts
• packages/cli/src/commands/postgres/usage.ts
• packages/cli/src/commands/project/context.ts
• packages/cli/src/commands/project/create.ts
• packages/cli/src/commands/project/delete.ts
• packages/cli/src/commands/project/env-add.ts
• packages/cli/src/commands/project/env-delete.ts
• packages/cli/src/commands/project/env-list.ts
• packages/cli/src/commands/project/env-shared.ts
• packages/cli/src/commands/project/env-update.ts
• packages/cli/src/commands/project/errors.ts
• packages/cli/src/commands/project/link.ts
• packages/cli/src/commands/project/list.ts
• packages/cli/src/commands/project/presentation.ts
• packages/cli/src/commands/project/rename.ts
• packages/cli/src/commands/project/show.ts
• packages/cli/src/commands/project/transfer.ts
• packages/cli/src/commands/service/errors.ts
• packages/cli/src/commands/service/target.ts
• packages/cli/src/commands/skills/family.ts
• packages/cli/src/controllers/app-env-api.ts
• packages/cli/src/controllers/app-env-file.ts
• packages/cli/src/controllers/app-env.ts
• packages/cli/src/controllers/branch.ts
• packages/cli/src/controllers/database.ts
• packages/cli/src/controllers/project.ts
• packages/cli/src/errors.ts
• packages/cli/src/legacy/output.ts
• packages/cli/src/lib/app/env-config.ts
• packages/cli/src/lib/app/env-errors.ts
• packages/cli/src/lib/app/env-file.ts
• packages/cli/src/lib/bucket/provider.ts
• packages/cli/src/lib/database/provider.ts
• packages/cli/src/lib/project/provider.ts
• packages/cli/src/lib/project/resolution.ts
• packages/cli/src/lib/project/setup.ts
• packages/cli/src/next-actions.ts
• packages/cli/tests/branch.test.ts
• packages/cli/tests/bucket.test.ts
• packages/cli/tests/database-plan-limit.test.ts
• packages/cli/tests/git.test.ts
• packages/cli/tests/postgres.test.ts
• packages/cli/tests/project-resolution.test.ts
• packages/cli/tests/project.test.ts
• packages/cli/tests/service-session.test.ts
• packages/cli/tests/update-check.test.ts
• scripts/list-error-codes.mjs

---

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.}

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@prisma/cli@234

npx https://pkg.pr.new/@prisma/cli-engine@234

commit: 1d2e5c7