Officialprisma/prisma-next1 file

Prisma Next Debug

Name: Prisma Next Debug
Availability: InStock
Author: prisma

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.

Use this skill View repository View on skills.sh

Specification

Skill ID: prisma/prisma-next/prisma-next-debug
Publisher: prisma
Repository: prisma-next
Installs: 237
Files: 1
Synced: Sep 24, 2026

How to use it

Open any RiverX project, open the Skills panel in the chat, and search for this identifier. The files are fetched from the source repository at install time.

prisma/prisma-next/prisma-next-debugInstalls these files

SKILL.md

What this skill tells the agent

Prisma Next — Debug

Edit your data contract. Prisma handles the rest.

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 mentions: Studio, EXPLAIN, query log, prepared statements, drift, hash mismatch, capability, planner.

When Not to Use

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):

{
  "ok": false,
  "code": "PN-MIG-2001",
  "domain": "MIG",
  "severity": "error",
  "summary": "Unfilled migration placeholder",
  "why": "...",
  "fix": "...",
  "where": { "path": "...", "line": 42 },
  "meta": { "slot": "..." },
  "docsUrl": "https://prisma-next.dev/..."
}

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):

{ name: 'RuntimeError', code: 'BUDGET.TIME_EXCEEDED', category: 'BUDGET', severity: 'error', message: '...', details: { ... } }

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

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-4001` Config file not found	Most `prisma-next` commands	Run `prisma-next init`, or pass `--config <path>`.
`PN-CLI-4002` Contract configuration missing	`contract emit`, `db *`	Add `contract: { ... }` to `prisma-next.config.ts`. See `prisma-next-contract`.
`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`.
`PN-CLI-4005` Database connection is required	`db *`, `migrate`, `migration status`	Pass `--db <url>` or set `db.connection` in `prisma-next.config.ts`.
`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`.
`PN-CLI-4020` Migration 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-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`.
`PN-MIG-2002` migration.ts not found	Reading a migration package	Restore from version control or scaffold a fresh package with `migration plan`.
`PN-MIG-2003` Invalid default export	Loading `migration.ts`	Use `export default class extends Migration { ... }` (or factory `() => ({ ... })`). See `prisma-next-migrations`.
`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.
`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).
`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`.

Use this skill in a project

Open any RiverX project, search the Skills panel for prisma/prisma-next/prisma-next-debug, and install it in one click.

Use this skill