Back to Details

prisma-next-debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Prisma Next — Debug

Prisma Next — 调试

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.
编辑你的数据契约，其余工作由Prisma处理。
当Prisma Next调用失败时，框架会返回一个结构化信封。该工具的作用是读取信封内容，根据
code
进行路由，并关联到对应的修复技能。本技能仅讲解信封结构和路由逻辑，不会重复其他兄弟技能的工作流。

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.
  • 用户粘贴了错误信封（CLI失败、运行时异常、
    --json
    输出）。
  • 用户反馈诸如“我的查询无法类型检查”、“我的迁移无法应用”、“emit失败”、“运行时崩溃”等问题。
  • 用户提到了稳定错误代码（如
    PN-CLI-*
    、
    PN-MIG-*
    、
    PN-RUN-*
    、
    PN-SCHEMA-*
    、
    MIGRATION.*
    、
    CONTRACT.*
    、
    LINT.*
    、
    BUDGET.*
    、
    PLAN.*
    、
    RUNTIME.*
    ）。
  • 用户提到以下内容：Studio、EXPLAIN、查询日志、预准备语句、架构漂移、哈希不匹配、功能、规划器。

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
    .
  • 用户想要编写查询/模型/迁移 → 使用对应的编写技能。
  • 用户想要预防错误（代码检查、预算控制、类型级防护） → 使用
    prisma-next-runtime
    。
  • 用户想要修改框架本身（因为没有可路由的信封、确实缺失功能） → 使用
    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
):
json
{
  "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
):
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.
Prisma Next会根据错误抛出的位置，生成两种不同的信封。在路由前请先确认你拿到的是哪一种。
1. CLI信封 — 由
prisma-next ...
命令生成（如emit、db init/update/verify/sign/schema、migration plan/apply/show/status、init）。结构参考
packages/1-framework/1-core/errors/src/control.ts
中的
CliErrorEnvelope
：
json
{
  "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/..."
}
完整代码格式为
PN-<domain>-<NNNN>
。当前使用的领域包括：
CLI
、
MIG
、
RUN
、
CON
、
SCHEMA
。严重程度分为
error | warn | info
— 当诊断结果为
warn
时，
migration status
命令会返回0，因此需要结合严重程度+错误代码进行路由，而不能仅依赖退出码。
2. 运行时信封 — 当执行查询时，由进程内运行时抛出。结构参考
packages/1-framework/1-core/framework-components/src/execution/runtime-error.ts
中的
RuntimeErrorEnvelope
：
ts
{ name: 'RuntimeError', code: 'BUDGET.TIME_EXCEEDED', category: 'BUDGET', severity: 'error', message: '...', details: { ... } }
category
可选值为
PLAN | CONTRACT | LINT | BUDGET | RUNTIME
（即
code
的前缀）。
details
字段包含结构化上下文（相当于CLI信封中的
meta
）。
3. SQL驱动错误 — 以
SqlQueryError
/ 
SqlConnectionError
形式呈现（参考
packages/2-sql/1-core/errors/
）。
SqlQueryError
的字段包括：
kind: 'sql_query'
、
sqlState
（Postgres SQLSTATE，例如
'23505'
）、
constraint
、
table
、
column
、
detail
、
cause
。这些错误没有
PN-*
代码 — 需要根据
sqlState
和约束元数据进行路由。SQL驱动错误通常会被中间件包装后再返回给用户，但原生SQL路径可能会直接暴露这些错误。

Wrapped errors and 
meta.code

包装错误与
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.
部分命令会将下游错误重新包装为
PN-RUN-3000
（
errorRuntime
）信封，并将原始代码存储在
meta.code
中。最常见的场景是：
migrate
命令通过
mapMigrationToolsError
包装
MigrationToolsError
（错误代码包括
MIGRATION.HASH_MISMATCH
、
MIGRATION.STALE_CONTRACT_BOOKENDS
、
MIGRATION.AMBIGUOUS_TARGET
）。此时你看到的信封是
code: 'PN-RUN-3000'
，而
meta.code: 'MIGRATION.HASH_MISMATCH'
。当错误代码为
PN-RUN-3000
时，务必检查
meta.code
 — 这里才是路由的关键信息。

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.
如果用户只粘贴了人工总结的内容，请要求他们提供
--json
输出（机器可读信封）或使用
-v
参数重新运行命令（CLI会打印完整的结构化字段）。
--json
和
-v
是所有CLI命令的全局参数。

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).
SymptomNext 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 exitOn 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).
这些症状不属于
PN-*
信封 — 需要根据消息文本进行路由，并关联到
prisma-next-runtime
的*Running as a script (teardown)*章节。
症状下一步操作
TypeError: db.end is not a function
运行时客户端不提供
db.end()
方法 — 这是
node-postgres
的连接池API（
pool.end()
）。正确的调用方式是
await db.close()
。参考
prisma-next-runtime
的*Running as a script (teardown)*章节。
查询执行完成后脚本挂起/进程无法退出在Postgres中，框架维护的
pg.Pool
会保持事件循环活跃。请在脚本返回前调用
await db.close()
，或者在脚本模块顶部使用
await using db = postgres<Contract>(...)
（请勿在请求处理器内部使用
await using
— 它是块级作用域，会导致每个请求结束后关闭连接）。参考
prisma-next-runtime
的*Running as a script (teardown)*章节。
Error('Postgres client is closed')
/ 
Error('SQLite client is closed')
/ 
Error('Mongo client is closed')
客户端已通过
db.close()
关闭（终端状态）。请移除提前调用的
close()
，调整顺序让
close()
在所有查询完成后执行，或者如果需要重新连接则创建新的
db
实例。参考
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.
CodeWhere it surfacesNext 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.missingExtensionPacks
to 
extensionPacks
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 packageRestore 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 planPass 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
.
PN-RUN-3003
Target mismatch		Runtime startupContract target ≠ config target; align them (see 
meta.expected
/ 
meta.actual
).
PN-RUN-3004
Schema verification failed
db verify
(full mode)		Inspect 
meta.verificationResult
. Run 
db update
to reconcile, or adjust contract.
PN-RUN-3010
Schema verification failed (CLI surface)
db verify
schema-only		Same as 3004.
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.
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.
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
).
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
/ 
.INVARIANTS_PENDING
migration status
info
diagnostics		Informational; exit 0. No action needed unless 
INVARIANTS_PENDING
matters for your CI gate. See 
prisma-next-migration-review
.
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.
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
.
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
.
PLAN.HASH_MISMATCH
Runtime, executing a precompiled planThe contract the plan was built against does not match the runtime contract. Re-emit, rebuild, redeploy.
CONTRACT.MARKER_MISSING
/ 
CONTRACT.MARKER_MISMATCH
Runtime, marker check before executingSame family as 
PN-RUN-3001
/ 
PN-RUN-3002
but raised in-process by the runtime rather than a CLI. Recovery is the same.
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.
SqlQueryError
(no 
PN-
code)		Raw-SQL paths surfacing a driver errorInspect 
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 firesCapability 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-timeRe-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
.
唯一的权威来源：读取信封内容，根据
code
（或包装错误的
meta.code
）找到对应行，执行下一步操作。
代码出现场景下一步操作
PN-CLI-4001
配置文件未找到		大多数
prisma-next
命令		运行
prisma-next init
，或通过
--config <path>
指定配置文件路径。
PN-CLI-4002
缺少契约配置
contract emit
、
db *
在
prisma-next.config.ts
中添加
contract: { ... }
配置。参考
prisma-next-contract
。
PN-CLI-4003
契约验证失败
contract emit
、
db *
修复
where.path
中指定的契约源后，重新运行
pnpm prisma-next contract emit
。参考
prisma-next-contract
。
PN-CLI-4005
需要数据库连接
db *
、
migrate
、
migration status
通过
--db <url>
参数指定，或在
prisma-next.config.ts
中设置
db.connection
。
PN-CLI-4011
配置中缺少扩展包
contract emit
（例如契约使用了
pgvector.Vector(...)
但配置中未列出pgvector扩展包）		将
meta.missingExtensionPacks
中指定的描述符添加到
prisma-next.config.ts
的
extensionPacks
中。参考
prisma-next-contract
。
PN-CLI-4020
迁移规划失败
db init
、
db update
检查
meta.conflicts
。需根据具体冲突进行恢复 — 关联到
prisma-next-migrations
。
PN-CLI-5002/5003/5004/…
初始化错误
prisma-next init
根据
meta.missingFlags
或
meta.allowed
中列出的缺失/无效参数，重新运行命令。
PN-MIG-2001
未填充迁移占位符
node migrations/app/<dir>/migration.ts
（自emit）或
migrate
编辑
migration.ts
，将指定的
placeholder("<slot>")
替换为真实的查询闭包，然后自emit。参考
prisma-next-migrations
。
PN-MIG-2002
未找到migration.ts		读取迁移包从版本控制中恢复，或使用
migration plan
生成新的迁移包。
PN-MIG-2003
无效默认导出		加载
migration.ts
使用
export default class extends Migration { ... }
（或工厂函数
() => ({ ... })
）。参考
prisma-next-migrations
。
PN-MIG-2005
dataTransform契约不匹配		构建数据转换查询计划将相同的
endContract
引用同时传递给
dataTransform(endContract, …)
和查询构建器上下文。
PN-RUN-3001
数据库未签名
db verify
、运行时启动		数据库尚未标记。运行
prisma-next db init --db <url>
（基线空数据库）或
db update --db <url>
（直接应用契约）。
PN-RUN-3002
哈希不匹配
db verify
、运行时启动		标记与契约哈希不一致。可以选择向前迁移（
migrate
/ 
db update
），或者如果数据库在手动修复后是正确的，则运行
db sign
。参考
prisma-next-migrations
。
PN-RUN-3003
目标不匹配		运行时启动契约目标与配置目标不一致；请对齐两者（参考
meta.expected
/ 
meta.actual
）。
PN-RUN-3004
架构验证失败
db verify
（完整模式）		检查
meta.verificationResult
。运行
db update
进行协调，或调整契约。
PN-RUN-3010
架构验证失败（CLI层面）
db verify
（仅架构）		与3004处理方式相同。
PN-RUN-3020
迁移执行器失败
migrate
、
db update
、
db init
检查
meta
中的冲突信息；协调架构漂移后重新运行。已应用的迁移会被保留。
PN-RUN-3030
破坏性变更需要确认
db update
（交互式提示触发；非交互式返回此代码）		添加
-y
（或
--yes
）参数重新运行以应用变更，或使用
--dry-run
预览变更。只有
db update
有此流程 — 
migrate
不会通过参数限制破坏性操作。
PN-RUN-3000
(包装器)
migrate
、其他包装
MigrationToolsError
的命令		读取
meta.code
。常见场景：
MIGRATION.HASH_MISMATCH
（重新执行：
node migrations/app/<dir>/migration.ts
）；
MIGRATION.AMBIGUOUS_TARGET
（并发迁移 — 使用
prisma-next-migration-review
）；
MIGRATION.STALE_CONTRACT_BOOKENDS
（重新运行
migration plan
）；
MIGRATION.NO_INVARIANT_PATH
/ 
MIGRATION.UNKNOWN_INVARIANT
（使用
prisma-next-migration-review
）。
PN-SCHEMA-0001
db verify
架构检查		实时架构不符合契约要求。
meta.verificationResult
包含差异信息。运行
db update
或调整契约。
MIGRATION.UP_TO_DATE
/ 
.DATABASE_BEHIND
/ 
.INVARIANTS_PENDING
migration status
的
info
级诊断信息		仅为提示信息；命令返回0。除非
INVARIANTS_PENDING
会影响CI检查，否则无需操作。参考
prisma-next-migration-review
。
MIGRATION.NO_MARKER
/ 
.MARKER_NOT_IN_HISTORY
/ 
.DIVERGED
/ 
CONTRACT.AHEAD
/ 
CONTRACT.UNREADABLE
migration status
的
warn
级诊断信息（命令返回0；CI检查需解析
--json
输出）		同时查看
severity
和
code
。
prisma-next-migration-review
涵盖了分支/漂移/标记不在历史记录中的处理流程。
BUDGET.ROWS_EXCEEDED
/ 
BUDGET.TIME_EXCEEDED
运行时，当
budgets
中间件启用时		调整
budgets({ maxRows, maxLatencyMs, ... })
配置，或重写查询。参考
prisma-next-runtime
。
LINT.SELECT_STAR
/ 
LINT.NO_LIMIT
/ 
LINT.DELETE_WITHOUT_WHERE
/ 
LINT.UPDATE_WITHOUT_WHERE
/ 
LINT.READ_ONLY_MUTATION
运行时，当
lints
中间件启用时		修复查询（添加
WHERE
/ 
LIMIT
/ 显式列），或放宽代码检查配置。参考
prisma-next-runtime
。
PLAN.HASH_MISMATCH
运行时，执行预编译计划时生成计划时使用的契约与运行时契约不一致。重新emit、重建并重新部署。
CONTRACT.MARKER_MISSING
/ 
CONTRACT.MARKER_MISMATCH
运行时，执行前的标记检查与
PN-RUN-3001
/ 
PN-RUN-3002
属于同一类错误，但由运行时在进程内抛出而非CLI。处理方式相同。
RUNTIME.ABORTED
（
details.phase
= 
encode|decode|stream|beforeExecute|afterExecute|onRow
）		运行时，
AbortSignal
在执行过程中触发		属于取消操作，而非错误；请将此信息返回给调用方。
SqlQueryError
（无
PN-
代码）		原生SQL路径暴露的驱动错误检查
sqlState
+ 
constraint
+ 
table
+ 
column
。Postgres的
23505
表示唯一约束冲突，
23503
表示外键约束冲突等。修复数据或架构。
TypeScript错误提到功能缺失（例如
returning()
不在类型中、从多加载中包含多关系）		编写阶段，尚未生成信封功能限制在契约中声明（
capabilities
块，按目标/家族命名空间），而非
prisma-next.config.ts
。关联到
prisma-next-contract
进行功能声明，关联到
prisma-next-queries
了解哪些方法受哪些功能限制。启用后重新emit（
pnpm prisma-next contract emit
）。
TypeScript错误提到
db.orm.<Model>
缺少字段/方法，或
Contract
结构过时		编写阶段重新emit（
pnpm prisma-next contract emit
）；确认
db.ts
使用
postgres<Contract, TypeMaps>(...)
实例化（类型参数会传播契约类型）。参考
prisma-next-runtime
和
prisma-next-contract
。
如果信封中的
code
不在此表中，请严格按照信封的
fix
字段执行 — 这是框架提供的官方下一步操作。如果
fix
为空或无帮助，请通过
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.
  1. 仅读取
    summary
    ，忽略信封的其他内容。     
    code
    、
    severity
    、
    why
    、
    fix
    、
    meta
    /
    details
    以及（CLI错误的）
    where
    都是关键信息。工具根据
    code
    进行路由，而用户通常只看到
    summary
    。
  2. 忽略
    severity
    。     
    migration status
    会输出warn级诊断信息，并且返回0。仅检查退出码的工具会错过所有并发迁移的警告。
  3. 跳过
    PN-RUN-3000
    的
    meta.code
    。     这个信封是包装器 — 真实的错误代码在
    meta.code
    中。
  4. 使用
    db sign
    来掩盖架构漂移。     
    db sign
    会根据当前契约哈希写入标记，但前提是架构验证必须通过。在使用
    db sign
    前，请先运行
    db verify
    。
  5. 部分失败后未检查状态就重新运行
    migrate
    。     
    db schema --db <url>
    会显示实时架构；
    migration status --db <url> --json
    会显示标记的实际位置。

What Prisma Next doesn't do yet

Prisma Next目前未支持的功能

  • 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
    .
  • Studio / GUI数据库浏览器。 暂无官方Studio。替代方案：使用
    prisma-next db schema
    查看CLI格式的实时架构树，或使用第三方工具（TablePlus、DataGrip、
    psql
    ）连接你的
    DATABASE_URL
    。如果需要内置GUI，请通过
    prisma-next-feedback
    提交功能请求。
  • 一流的查询日志中间件。 框架未内置“记录所有查询”的中间件。替代方案：编写一个小型自定义中间件包装每个操作（参考
    prisma-next-runtime
    的中间件组合）。如果需要内置查询日志，请通过
    prisma-next-feedback
    提交功能请求。
  • EXPLAIN集成。 计划中没有一流的
    .explain()
    方法。替代方案：将EXPLAIN作为原生查询编写（
    db.sql.raw\
    EXPLAIN ANALYZE ...`
    ；参考
    prisma-next-queries
    ）。如果需要一流的EXPLAIN支持，请通过
    prisma-next-feedback`提交功能请求。
  • 面向用户的预准备语句缓存。 适配器会为参数化语句在底层进行预准备，但你无法通过名称预准备和重新执行语句。替代方案：使用TypedSQL（参考
    prisma-next-queries
    ）。如果需要将预准备语句作为一流API，请通过
    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.
  1. 使用
    -v
    （或
    --json
    获取机器可读输出）重新运行命令，获取完整信封。
  2. 如果信封确实信息不足 — 
    fix
    为空、缺少
    meta
    、
    summary
    泛化 — 这属于框架的功能缺口；请将信封、契约源（已脱敏）和复现步骤提交给
    prisma-next-feedback
    。

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
    .
  • 识别信封类型（
    CliErrorEnvelope
    、
    RuntimeErrorEnvelope
    、
    SqlQueryError
    ）。
  • 读取所有字段 — 
    code
    、
    severity
    、
    why
    、
    fix
    、
    meta
    （或
    details
    ）、
    where
    （如果存在）。
  • 如果
    code
    是
    PN-RUN-3000
    ，同时读取
    meta.code
    。
  • 根据
    code
    路由到下一步操作（并按照表格说明关联到对应的编写技能）。
  • 使用相关CLI命令重新验证（
    db verify
    、
    migration status --json
    、
    contract emit
    、
    migrate
    ）。
  • 未虚构Studio / EXPLAIN / 查询日志API — 使用文档中的替代方案，并将未满足的功能缺口路由到
    prisma-next-feedback
    。