prisma-next-debug

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

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.

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

1. 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.
2. Ignoring severity. migration status emits warn-level diagnostics and exits 0. An agent that only checks exit code misses every concurrent-migration warning.
3. Skipping meta.code on PN-RUN-3000. That envelope is a wrapper — the real code lives on meta.code.
4. 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.
5. 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

1. Re-run with -v (or --json for machine output) to get the full envelope.
2. 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.