When a Prisma Next call fails, the framework returns a structured envelope. The agent's job is to read the envelope, route on the code, and chain to the right authoring skill for the actual fix. This skill teaches the envelope shapes and the routing — it does not duplicate sibling-skill workflows.
When to Use
User pastes an error envelope (CLI failure, runtime exception, --json output).
User says "my query won't typecheck", "my migration won't apply", "my emit failed", "the runtime crashed".
User mentions a stable code (PN-CLI-*, PN-MIG-*, PN-RUN-*, PN-SCHEMA-*, MIGRATION.*, CONTRACT.*, LINT.*, BUDGET.*, PLAN.*, RUNTIME.*).
User wants to author a query / model / migration → the matching authoring skill.
User wants to prevent errors (lints, budgets, type-level guards) → prisma-next-runtime.
User wants the framework changed because the surface itself is the problem (no envelope to route on, capability genuinely missing) → prisma-next-feedback.
Key Concepts
Two envelope shapes
Prisma Next emits two distinct envelopes depending on which seam threw. Read which one you have before routing.
1. CLI envelope — produced by prisma-next ... commands (emit, db init/update/verify/sign/schema, migration plan/apply/show/status, init). Shape (see CliErrorEnvelope in packages/1-framework/1-core/errors/src/control.ts):
The full code is PN-<domain>-<NNNN>. Domains in use: CLI, MIG, RUN, CON, SCHEMA. Severity is error | warn | info — migration status exits 0 when its diagnostics are warn, so route on severity + code together, not on exit code alone.
2. Runtime envelope — thrown by the in-process runtime when executing a query (see RuntimeErrorEnvelope in packages/1-framework/1-core/framework-components/src/execution/runtime-error.ts):
category is one of PLAN | CONTRACT | LINT | BUDGET | RUNTIME (the prefix of code). details holds the structured context (details is the runtime envelope's equivalent of the CLI envelope's meta).
3. SQL driver errors — surface as SqlQueryError / SqlConnectionError (see packages/2-sql/1-core/errors/). Fields on SqlQueryError: kind: 'sql_query', sqlState (Postgres SQLSTATE, e.g. '23505'), constraint, table, column, detail, cause. These are notPN-* codes — route on sqlState and the constraint metadata. SQL driver errors are typically wrapped by middleware before reaching the user, but raw-SQL paths can surface them directly.
Wrapped errors and meta.code
Some commands re-wrap a downstream error into a PN-RUN-3000 (errorRuntime) envelope and stash the original code on meta.code. The most important case: migrate wraps MigrationToolsError (which has codes like MIGRATION.HASH_MISMATCH, MIGRATION.STALE_CONTRACT_BOOKENDS, MIGRATION.AMBIGUOUS_TARGET) via mapMigrationToolsError. The envelope you see is code: 'PN-RUN-3000' with meta.code: 'MIGRATION.HASH_MISMATCH'. Always check meta.code when code is PN-RUN-3000 — that's where the routing-quality information lives.
How to ask for the full envelope
If the user only pasted the human summary, ask for --json output (machine envelope) or re-run with -v (CLI prints the full structured fields). --json and -v are global flags on every CLI command.
Routing — script teardown and closed client
These symptoms are not PN-* envelopes — route on the message text and chain to prisma-next-runtime § Running as a script (teardown).
Symptom
Next move
TypeError: db.end is not a function
The runtime client does not expose db.end() — that's the node-postgres pool API (pool.end()). The right call is await db.close(). See prisma-next-runtime § Running as a script (teardown).
Script hangs after queries print / process won't exit
On Postgres the façade-owned pg.Pool keeps the event loop alive. Call await db.close() before the script returns, or await using db = postgres<Contract>(...) at the top of a script module (do NOT put await using inside a request handler — block-scoped, would close per-request). See prisma-next-runtime § Running as a script (teardown).
Error('Postgres client is closed') / Error('SQLite client is closed') / Error('Mongo client is closed')
The client was closed via db.close() (terminal state). Remove the early close(), reorder so close() runs last after all queries, or construct a new db if reconnection is intended. See prisma-next-runtime § Running as a script (teardown).
Routing — symptom and code → next move
The single source of truth: read the envelope, find the row by code (or meta.code for wrapped errors), follow the next move.
Code
Where it surfaces
Next move
PN-CLI-4001Config file not found
Most prisma-next commands
Run prisma-next init, or pass --config <path>.
PN-CLI-4002Contract configuration missing
contract emit, db *
Add contract: { ... } to prisma-next.config.ts. See prisma-next-contract.
PN-CLI-4003Contract validation failed
contract emit, db *
Re-run pnpm prisma-next contract emit after fixing the contract source named in where.path. See prisma-next-contract.
PN-CLI-4005Database connection is required
db *, migrate, migration status
Pass --db <url> or set db.connection in prisma-next.config.ts.
PN-CLI-4011Missing extension packs in config
contract emit (e.g. contract uses pgvector.Vector(...) but config does not list the pgvector pack)
Add the descriptors named in meta.missingExtensions to extensions in prisma-next.config.ts. See prisma-next-contract.
PN-CLI-4020Migration planning failed
db init, db update
Inspect meta.conflicts. Recovery is per-conflict — chain to prisma-next-migrations.
PN-CLI-5002/5003/5004/…Init errors
prisma-next init
Re-run with the missing/invalid flags listed in meta.missingFlags or meta.allowed.
PN-MIG-2001Unfilled migration placeholder
node migrations/app/<dir>/migration.ts (self-emit) or migrate
Edit migration.ts, replace the named placeholder("<slot>") with a real query closure, self-emit. See prisma-next-migrations.
PN-MIG-2002migration.ts not found
Reading a migration package
Restore from version control or scaffold a fresh package with migration plan.
PN-MIG-2003Invalid default export
Loading migration.ts
Use export default class extends Migration { ... } (or factory () => ({ ... })). See prisma-next-migrations.
PN-MIG-2005dataTransform contract mismatch
Building a data-transform query plan
Pass the same endContract reference to both dataTransform(endContract, …) and the query-builder context.
PN-RUN-3001Database not signed
db verify, runtime startup
DB has no marker yet. Run prisma-next db init --db <url> (baseline empty DB) or db update --db <url> (apply contract directly).
PN-RUN-3002Hash mismatch
db verify, runtime startup
Marker disagrees with contract hash. Either migrate forward (migrate / db update), or — if the DB is correct after a manual fix-up — db sign. See prisma-next-migrations.
PN-RUN-3003Target mismatch
Runtime startup
Contract target ≠ config target; align them (see meta.expected / meta.actual).
PN-RUN-3004Schema verification failed
db verify (full mode)
Inspect meta.verificationResult. Run db update to reconcile, or adjust contract.
db update (interactive prompt fires; non-interactive returns this code)
Re-run with -y (or --yes) to apply, or --dry-run to preview. Only db update has this flow — migrate does not gate destructive ops on a flag.
PN-RUN-3000(wrapper)
migrate, others wrapping MigrationToolsError
Read meta.code. Cases: MIGRATION.HASH_MISMATCH (re-emit: node migrations/app/<dir>/migration.ts); MIGRATION.AMBIGUOUS_TARGET (concurrent migrations — prisma-next-migration-review); MIGRATION.STALE_CONTRACT_BOOKENDS (re-run migration plan); MIGRATION.NO_INVARIANT_PATH / MIGRATION.UNKNOWN_INVARIANT (prisma-next-migration-review); MIGRATION.PATH_UNREACHABLE / MIGRATION.MARKER_MISMATCH (run migrate --show --db $URL to inspect the path, then migration plan --from <from> --to <target> or migration list to audit the graph — see prisma-next-migration-review).
PN-SCHEMA-0001
db verify schema check
Live schema does not satisfy contract. meta.verificationResult has the diff. Run db update or adjust the contract.
MIGRATION.UP_TO_DATE / .DATABASE_BEHIND
migration statusinfo diagnostics
Informational; exit 0. See prisma-next-migration-review.
MIGRATION.MISSING_INVARIANTS
migration statusinfo diagnostic
The live marker reached the destination hash structurally but doesn't carry all invariants the target ref requires. Run migrate --to <name> --db $URL to take a path that covers the missing invariants. See prisma-next-migration-review.
Inspect sqlState + constraint + table + column. Postgres 23505 = unique violation, 23503 = foreign-key violation, etc. Fix the data or the schema.
TypeScript error mentioning a capability (e.g. returning() not on the type, include of a many-relation off a many-load)
Authoring-time, before any envelope fires
Capability gates are declared in the contract (capabilities block, namespaced by target/family), not in prisma-next.config.ts. Route to prisma-next-contract for capability declaration and to prisma-next-queries for which method gates on which capability. Re-emit (pnpm prisma-next contract emit) after enabling.
TypeScript error mentioning a missing field/method on db.orm.<Model> or a stale Contract shape
Authoring-time
Re-emit (pnpm prisma-next contract emit); confirm db.ts instantiates with postgres<Contract, TypeMaps>(...) (the type parameters propagate the contract types). See prisma-next-runtime and prisma-next-contract.
If the envelope's code is not in this table, follow the envelope's fix field literally — it's the framework's first-party next move. If fix is empty or unhelpful, escalate via prisma-next-feedback.
Common Pitfalls
Reading only summary, not the rest of the envelope.code, severity, why, fix, meta/details, and (for CLI errors) where are all load-bearing. The agent routes on code; the user sees summary.
Ignoring severity.migration status emits warn-level diagnostics and exits 0. An agent that only checks exit code misses every concurrent-migration warning.
Skipping meta.code on PN-RUN-3000. That envelope is a wrapper — the real code lives on meta.code.
Treating drift as something to silence with db sign.db sign writes the marker from the current contract hash, but it requires schema verification to pass first. Run db verify before reaching for db sign.
Re-running migrate after a partial failure without inspecting state.db schema --db <url> shows the live shape; migration status --db <url> --json shows where the marker actually is.
What Prisma Next doesn't do yet
Studio / GUI database browser. No first-party Studio. Workaround: prisma-next db schema for a CLI tree of the live schema, or use a third-party tool (TablePlus, DataGrip, psql) against your DATABASE_URL. If you need a built-in GUI, file a feature request via prisma-next-feedback.
First-class query logger middleware. No built-in "log every query" middleware ships with the framework. Workaround: write a small custom middleware that wraps each operation (see prisma-next-runtime for middleware composition). If you need a built-in query log, file a feature request via prisma-next-feedback.
EXPLAIN integration. No first-class .explain() on plans. Workaround: write the EXPLAIN as a raw query (db.sql.raw\EXPLAIN ANALYZE ...`; see prisma-next-queries). If you need first-class EXPLAIN, file a feature request via prisma-next-feedback`.
Prepared-statement caching as a user-facing surface. Adapters prepare under the hood for parameterized queries, but you cannot pre-prepare and re-execute a statement by name. Workaround: use TypedSQL (see prisma-next-queries). If you need prepared statements as a first-class API, file a feature request via prisma-next-feedback.
Asking for help when the envelope doesn't route
Re-run with -v (or --json for machine output) to get the full envelope.
If the envelope is genuinely uninformative — empty fix, missing meta, generic summary — that's a framework affordance gap; route to prisma-next-feedback with the envelope, the contract source (sanitised), and the reproduction steps.
Checklist
Identified which envelope shape (CliErrorEnvelope, RuntimeErrorEnvelope, SqlQueryError).
Read every field — code, severity, why, fix, meta (or details), where if present.
If code is PN-RUN-3000, also read meta.code.
Routed on code to the next move (and chained to the matching authoring skill where the table says so).
Re-verified with the relevant CLI command (db verify, migration status --json, contract emit, migrate).
Did not confabulate a Studio / EXPLAIN / query-log API — used the documented workaround and routed unmet capability gaps to prisma-next-feedback.
1---2name: prisma-next-debug3description: Read a Prisma Next structured error envelope and route to the right recovery — code, domain, severity, why, fix, meta. Use for error, exception, my emit failed, my query won't typecheck, my query crashed, my migration won't apply, MIGRATION.HASH_MISMATCH, BUDGET.ROWS_EXCEEDED, BUDGET.TIME_EXCEEDED, RUNTIME.ABORTED, PLAN.HASH_MISMATCH, CONTRACT.MARKER_MISSING, PN-RUN-3001, PN-RUN-3002, PN-RUN-3030, PN-MIG-2001, PN-CLI-4011, PN-SCHEMA-0001, drift, capability missing, planner conflict, prisma studio, EXPLAIN, query log, db.end, db.close, script won't exit, hangs, close connection, pool.end, client is closed.4---56# Prisma Next — Debug
78> **Edit your data contract. Prisma handles the rest.**
910When a Prisma Next call fails, the framework returns a **structured envelope**. The agent's job is to read the envelope, route on the `code`, and chain to the right authoring skill for the actual fix. This skill teaches the envelope shapes and the routing — it does not duplicate sibling-skill workflows.
1112## When to Use
1314- User pastes an error envelope (CLI failure, runtime exception, `--json` output).
15- User says *"my query won't typecheck"*, *"my migration won't apply"*, *"my emit failed"*, *"the runtime crashed"*.
16- User mentions a stable code (`PN-CLI-*`, `PN-MIG-*`, `PN-RUN-*`, `PN-SCHEMA-*`, `MIGRATION.*`, `CONTRACT.*`, `LINT.*`, `BUDGET.*`, `PLAN.*`, `RUNTIME.*`).
17- User mentions: *Studio, EXPLAIN, query log, prepared statements, drift, hash mismatch, capability, planner*.
1819## When Not to Use
2021- User wants to author a query / model / migration → the matching authoring skill.
22- User wants to *prevent* errors (lints, budgets, type-level guards) → `prisma-next-runtime`.
23- User wants the framework changed because the surface itself is the problem (no envelope to route on, capability genuinely missing) → `prisma-next-feedback`.
2425## Key Concepts
2627### Two envelope shapes
2829Prisma Next emits **two distinct envelopes** depending on which seam threw. Read which one you have *before* routing.
3031**1. CLI envelope** — produced by `prisma-next ...` commands (emit, db init/update/verify/sign/schema, migration plan/apply/show/status, init). Shape (see `CliErrorEnvelope` in `packages/1-framework/1-core/errors/src/control.ts`):
3233```json
34{
35 "ok": false,
36 "code": "PN-MIG-2001",
37 "domain": "MIG",
38 "severity": "error",
39 "summary": "Unfilled migration placeholder",
40 "why": "...",
41 "fix": "...",
42 "where": { "path": "...", "line": 42 },
43 "meta": { "slot": "..." },
44 "docsUrl": "https://prisma-next.dev/..."
45}
46```
4748The full code is `PN-<domain>-<NNNN>`. Domains in use: `CLI`, `MIG`, `RUN`, `CON`, `SCHEMA`. Severity is `error | warn | info` — `migration status` exits 0 when its diagnostics are `warn`, so route on **severity + code together**, not on exit code alone.
4950**2. Runtime envelope** — thrown by the in-process runtime when executing a query (see `RuntimeErrorEnvelope` in `packages/1-framework/1-core/framework-components/src/execution/runtime-error.ts`):
5152```ts
53{ name: 'RuntimeError', code: 'BUDGET.TIME_EXCEEDED', category: 'BUDGET', severity: 'error', message: '...', details: { ... } }
54```
5556`category` is one of `PLAN | CONTRACT | LINT | BUDGET | RUNTIME` (the prefix of `code`). `details` holds the structured context (`details` is the runtime envelope's equivalent of the CLI envelope's `meta`).
5758**3. SQL driver errors** — surface as `SqlQueryError` / `SqlConnectionError` (see `packages/2-sql/1-core/errors/`). Fields on `SqlQueryError`: `kind: 'sql_query'`, `sqlState` (Postgres SQLSTATE, e.g. `'23505'`), `constraint`, `table`, `column`, `detail`, `cause`. These are *not* `PN-*` codes — route on `sqlState` and the constraint metadata. SQL driver errors are typically wrapped by middleware before reaching the user, but raw-SQL paths can surface them directly.
5960### Wrapped errors and `meta.code`
6162Some commands re-wrap a downstream error into a `PN-RUN-3000` (`errorRuntime`) envelope and stash the original code on `meta.code`. The most important case: `migrate` wraps `MigrationToolsError` (which has codes like `MIGRATION.HASH_MISMATCH`, `MIGRATION.STALE_CONTRACT_BOOKENDS`, `MIGRATION.AMBIGUOUS_TARGET`) via `mapMigrationToolsError`. The envelope you see is `code: 'PN-RUN-3000'` with `meta.code: 'MIGRATION.HASH_MISMATCH'`. **Always check `meta.code` when `code` is `PN-RUN-3000`** — that's where the routing-quality information lives.
6364### How to ask for the full envelope
6566If the user only pasted the human summary, ask for `--json` output (machine envelope) or re-run with `-v` (CLI prints the full structured fields). `--json` and `-v` are global flags on every CLI command.
6768## Routing — script teardown and closed client
6970These symptoms are not `PN-*` envelopes — route on the message text and chain to `prisma-next-runtime` § *Running as a script (teardown)*.
7172| Symptom | Next move |
73|---|---|
74| `TypeError: db.end is not a function` | The runtime client does not expose `db.end()` — that's the `node-postgres` pool API (`pool.end()`). The right call is `await db.close()`. See `prisma-next-runtime` § *Running as a script (teardown)*. |
75| Script hangs after queries print / process won't exit | On Postgres the façade-owned `pg.Pool` keeps the event loop alive. Call `await db.close()` before the script returns, or `await using db = postgres<Contract>(...)` at the top of a script module (do NOT put `await using` inside a request handler — block-scoped, would close per-request). See `prisma-next-runtime` § *Running as a script (teardown)*. |
76| `Error('Postgres client is closed')` / `Error('SQLite client is closed')` / `Error('Mongo client is closed')` | The client was closed via `db.close()` (terminal state). Remove the early `close()`, reorder so `close()` runs last after all queries, or construct a new `db` if reconnection is intended. See `prisma-next-runtime` § *Running as a script (teardown)*. |
7778## Routing — symptom and code → next move
7980The single source of truth: read the envelope, find the row by `code` (or `meta.code` for wrapped errors), follow the next move.
8182| Code | Where it surfaces | Next move |
83|---|---|---|
84| `PN-CLI-4001` *Config file not found* | Most `prisma-next` commands | Run `prisma-next init`, or pass `--config <path>`. |
85| `PN-CLI-4002` *Contract configuration missing* | `contract emit`, `db *` | Add `contract: { ... }` to `prisma-next.config.ts`. See `prisma-next-contract`. |
86| `PN-CLI-4003` *Contract validation failed* | `contract emit`, `db *` | Re-run `pnpm prisma-next contract emit` after fixing the contract source named in `where.path`. See `prisma-next-contract`. |
87| `PN-CLI-4005` *Database connection is required* | `db *`, `migrate`, `migration status` | Pass `--db <url>` or set `db.connection` in `prisma-next.config.ts`. |
88| `PN-CLI-4011` *Missing extension packs in config* | `contract emit` (e.g. contract uses `pgvector.Vector(...)` but config does not list the pgvector pack) | Add the descriptors named in `meta.missingExtensions` to `extensions` in `prisma-next.config.ts`. See `prisma-next-contract`. |
89| `PN-CLI-4020` *Migration planning failed* | `db init`, `db update` | Inspect `meta.conflicts`. Recovery is per-conflict — chain to `prisma-next-migrations`. |
90| `PN-CLI-5002/5003/5004/…` *Init errors* | `prisma-next init` | Re-run with the missing/invalid flags listed in `meta.missingFlags` or `meta.allowed`. |
91| `PN-MIG-2001` *Unfilled migration placeholder* | `node migrations/app/<dir>/migration.ts` (self-emit) or `migrate` | Edit `migration.ts`, replace the named `placeholder("<slot>")` with a real query closure, self-emit. See `prisma-next-migrations`. |
92| `PN-MIG-2002` *migration.ts not found* | Reading a migration package | Restore from version control or scaffold a fresh package with `migration plan`. |
93| `PN-MIG-2003` *Invalid default export* | Loading `migration.ts` | Use `export default class extends Migration { ... }` (or factory `() => ({ ... })`). See `prisma-next-migrations`. |
94| `PN-MIG-2005` *dataTransform contract mismatch* | Building a data-transform query plan | Pass the same `endContract` reference to both `dataTransform(endContract, …)` and the query-builder context. |
95| `PN-RUN-3001` *Database not signed* | `db verify`, runtime startup | DB has no marker yet. Run `prisma-next db init --db <url>` (baseline empty DB) or `db update --db <url>` (apply contract directly). |
96| `PN-RUN-3002` *Hash mismatch* | `db verify`, runtime startup | Marker disagrees with contract hash. Either migrate forward (`migrate` / `db update`), or — if the DB is correct after a manual fix-up — `db sign`. See `prisma-next-migrations`. |
97| `PN-RUN-3003` *Target mismatch* | Runtime startup | Contract target ≠ config target; align them (see `meta.expected` / `meta.actual`). |
98| `PN-RUN-3004` *Schema verification failed* | `db verify` (full mode) | Inspect `meta.verificationResult`. Run `db update` to reconcile, or adjust contract. |
99| `PN-RUN-3010` *Schema verification failed (CLI surface)* | `db verify` schema-only | Same as 3004. |
100| `PN-RUN-3020` *Migration runner failed* | `migrate`, `db update`, `db init` | Inspect `meta` for the conflict; reconcile schema drift, then re-run. Previously applied migrations are preserved. |
101| `PN-RUN-3030` *Destructive changes require confirmation* | `db update` (interactive prompt fires; non-interactive returns this code) | Re-run with `-y` (or `--yes`) to apply, or `--dry-run` to preview. **Only `db update` has this flow** — `migrate` does not gate destructive ops on a flag. |
102| `PN-RUN-3000` *(wrapper)* | `migrate`, others wrapping `MigrationToolsError` | Read `meta.code`. Cases: `MIGRATION.HASH_MISMATCH` (re-emit: `node migrations/app/<dir>/migration.ts`); `MIGRATION.AMBIGUOUS_TARGET` (concurrent migrations — `prisma-next-migration-review`); `MIGRATION.STALE_CONTRACT_BOOKENDS` (re-run `migration plan`); `MIGRATION.NO_INVARIANT_PATH` / `MIGRATION.UNKNOWN_INVARIANT` (`prisma-next-migration-review`); `MIGRATION.PATH_UNREACHABLE` / `MIGRATION.MARKER_MISMATCH` (run `migrate --show --db $URL` to inspect the path, then `migration plan --from <from> --to <target>` or `migration list` to audit the graph — see `prisma-next-migration-review`). |
103| `PN-SCHEMA-0001` | `db verify` schema check | Live schema does not satisfy contract. `meta.verificationResult` has the diff. Run `db update` or adjust the contract. |
104| `MIGRATION.UP_TO_DATE` / `.DATABASE_BEHIND` | `migration status` `info` diagnostics | Informational; exit 0. See `prisma-next-migration-review`. |
105| `MIGRATION.MISSING_INVARIANTS` | `migration status` `info` diagnostic | The live marker reached the destination hash structurally but doesn't carry all invariants the target ref requires. Run `migrate --to <name> --db $URL` to take a path that covers the missing invariants. See `prisma-next-migration-review`. |
106| `MIGRATION.NO_MARKER` / `.MARKER_NOT_IN_HISTORY` / `.DIVERGED` / `CONTRACT.AHEAD` / `CONTRACT.UNREADABLE` | `migration status` `warn` diagnostics (exit 0; CI gates parse `--json`) | Read `severity` *and* `code`. `prisma-next-migration-review` covers the diamond/diverged/marker-out-of-history flows. |
107| `BUDGET.ROWS_EXCEEDED` / `BUDGET.TIME_EXCEEDED` | Runtime, when the `budgets` middleware is active | Tune `budgets({ maxRows, maxLatencyMs, ... })` or rewrite the query. See `prisma-next-runtime`. |
108| `LINT.SELECT_STAR` / `LINT.NO_LIMIT` / `LINT.DELETE_WITHOUT_WHERE` / `LINT.UPDATE_WITHOUT_WHERE` / `LINT.READ_ONLY_MUTATION` | Runtime, when the `lints` middleware is active | Fix the query (add a `WHERE` / `LIMIT` / explicit columns), or relax the lint config. See `prisma-next-runtime`. |
109| `PLAN.HASH_MISMATCH` | Runtime, executing a precompiled plan | The contract the plan was built against does not match the runtime contract. Re-emit, rebuild, redeploy. |
110| `CONTRACT.MARKER_MISSING` / `CONTRACT.MARKER_MISMATCH` | Runtime, marker check before executing | Same family as `PN-RUN-3001` / `PN-RUN-3002` but raised in-process by the runtime rather than a CLI. Recovery is the same. |
111| `RUNTIME.ABORTED` (`details.phase` = `encode\|decode\|stream\|beforeExecute\|afterExecute\|onRow`) | Runtime, when an `AbortSignal` fires mid-execute | Cancellation, not a bug; surface to the caller. |
112| `SqlQueryError` (no `PN-` code) | Raw-SQL paths surfacing a driver error | Inspect `sqlState` + `constraint` + `table` + `column`. Postgres `23505` = unique violation, `23503` = foreign-key violation, etc. Fix the data or the schema. |
113| TypeScript error mentioning a capability (e.g. `returning()` not on the type, `include` of a many-relation off a many-load) | Authoring-time, before any envelope fires | Capability gates are declared in the **contract** (`capabilities` block, namespaced by target/family), not in `prisma-next.config.ts`. Route to `prisma-next-contract` for capability declaration and to `prisma-next-queries` for which method gates on which capability. Re-emit (`pnpm prisma-next contract emit`) after enabling. |
114| TypeScript error mentioning a missing field/method on `db.orm.<Model>` or a stale `Contract` shape | Authoring-time | Re-emit (`pnpm prisma-next contract emit`); confirm `db.ts` instantiates with `postgres<Contract, TypeMaps>(...)` (the type parameters propagate the contract types). See `prisma-next-runtime` and `prisma-next-contract`. |
115116If the envelope's `code` is not in this table, follow the envelope's `fix` field literally — it's the framework's first-party next move. If `fix` is empty or unhelpful, escalate via `prisma-next-feedback`.
117118## Common Pitfalls
1191201. **Reading only `summary`, not the rest of the envelope.** `code`, `severity`, `why`, `fix`, `meta`/`details`, and (for CLI errors) `where` are all load-bearing. The agent routes on `code`; the user sees `summary`.
1212. **Ignoring `severity`.** `migration status` emits warn-level diagnostics and **exits 0**. An agent that only checks exit code misses every concurrent-migration warning.
1223. **Skipping `meta.code` on `PN-RUN-3000`.** That envelope is a wrapper — the real code lives on `meta.code`.
1234. **Treating drift as something to silence with `db sign`.** `db sign` writes the marker from the current contract hash, but it requires schema verification to pass first. Run `db verify` before reaching for `db sign`.
1245. **Re-running `migrate` after a partial failure without inspecting state.** `db schema --db <url>` shows the live shape; `migration status --db <url> --json` shows where the marker actually is.
125126## What Prisma Next doesn't do yet
127128- **Studio / GUI database browser.** No first-party Studio. Workaround: `prisma-next db schema` for a CLI tree of the live schema, or use a third-party tool (TablePlus, DataGrip, `psql`) against your `DATABASE_URL`. If you need a built-in GUI, file a feature request via `prisma-next-feedback`.
129- **First-class query logger middleware.** No built-in "log every query" middleware ships with the framework. Workaround: write a small custom middleware that wraps each operation (see `prisma-next-runtime` for middleware composition). If you need a built-in query log, file a feature request via `prisma-next-feedback`.
130- **`EXPLAIN` integration.** No first-class `.explain()` on plans. Workaround: write the EXPLAIN as a raw query (`db.sql.raw\`EXPLAIN ANALYZE ...\``; see `prisma-next-queries`). If you need first-class EXPLAIN, file a feature request via `prisma-next-feedback`.
131- **Prepared-statement caching as a user-facing surface.** Adapters prepare under the hood for parameterized queries, but you cannot pre-prepare and re-execute a statement by name. Workaround: use TypedSQL (see `prisma-next-queries`). If you need prepared statements as a first-class API, file a feature request via `prisma-next-feedback`.
132133## Asking for help when the envelope doesn't route
1341351. Re-run with `-v` (or `--json` for machine output) to get the full envelope.
1362. If the envelope is genuinely uninformative — empty `fix`, missing `meta`, generic `summary` — that's a framework affordance gap; route to `prisma-next-feedback` with the envelope, the contract source (sanitised), and the reproduction steps.
137138## Checklist
139140- [ ] Identified which envelope shape (`CliErrorEnvelope`, `RuntimeErrorEnvelope`, `SqlQueryError`).
141- [ ] Read every field — `code`, `severity`, `why`, `fix`, `meta` (or `details`), `where` if present.
142- [ ] If `code` is `PN-RUN-3000`, also read `meta.code`.
143- [ ] Routed on `code` to the next move (and chained to the matching authoring skill where the table says so).
144- [ ] Re-verified with the relevant CLI command (`db verify`, `migration status --json`, `contract emit`, `migrate`).
145- [ ] Did not confabulate a Studio / EXPLAIN / query-log API — used the documented workaround and routed unmet capability gaps to `prisma-next-feedback`.
Run npx skillmds add prisma-prisma-next/prisma-next-debug in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Read a Prisma Next structured error envelope and route to the right recovery — code, domain, severity, why, fix, meta. Use for error, exception, my emit failed, my query won't typecheck, my query crashed, my migration won't apply, MIGRATION.HASH_MISMATCH, BUDGET.ROWS_EXCEEDED, BUDGET.TIME_EXCEEDED, RUNTIME.ABORTED, PLAN.HASH_MISMATCH, CONTRACT.MARKER_MISSING, PN-RUN-3001, PN-RUN-3002, PN-RUN-3030, PN-MIG-2001, PN-CLI-4011, PN-SCHEMA-0001, drift, capability missing, planner conflict, prisma studio, EXPLAIN, query log, db.end, db.close, script won't exit, hangs, close connection, pool.end, client is closed. It is listed under Finance & Business on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
prisma (@prisma-prisma-next) published this skill. Their other Agent Skills are listed on their SkillMD profile.
prisma