prisma-next-debug

Prisma Next — デバッグ

データコントラクトを編集すれば、あとは Prisma が処理します。

Prisma Next の呼び出しが失敗すると、フレームワークは構造化エンベロープを返します。エージェントの役割は、エンベロープを読み取り、code に基づいて適切な作成スキルにつなぎ、実際の修正を行うことです。このスキルでは、エンベロープの形式とルーティングについて説明します。関連する別のスキルのワークフローを重複して説明するものではありません。

使用する場面

• ユーザーがエラーエンベロープ（CLI の失敗、実行時例外、--json の出力）を貼り付けた場合。
• ユーザーが 「クエリの型チェックが通らない」、「マイグレーションを適用できない」、「emit が失敗した」、「ランタイムがクラッシュした」 と述べた場合。
• ユーザーが安定したコード（PN-CLI-*、PN-MIG-*、PN-RUN-*、PN-SCHEMA-*、MIGRATION.*、CONTRACT.*、LINT.*、BUDGET.*、PLAN.*、RUNTIME.*）に言及した場合。
• ユーザーが Studio、EXPLAIN、クエリログ、プリペアドステートメント、ドリフト、ハッシュの不一致、ケイパビリティ、プランナー に言及した場合。

使用しない場面

• ユーザーがクエリ／モデル／マイグレーションを作成したい場合 → 該当する作成スキルを使用します。
• ユーザーがエラーの予防（リント、予算、型レベルのガード）を望む場合 → prisma-next-runtime を使用します。
• サーフェス自体に問題があり、フレームワークの変更を望む場合（ルーティング可能なエンベロープがない、必要なケイパビリティが本当に欠けている） → prisma-next-feedback を使用します。

主な概念

2 種類のエンベロープ形式

Prisma Next は、例外が発生した接続点に応じて異なる 2 種類のエンベロープを出力します。ルーティングする前に、どちらの形式かを確認してください。

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 を参照）：

{
  "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 です。migration status は診断結果が warn の場合に終了コード 0 を返すため、終了コードだけでなく、重大度とコードの両方に基づいてルーティングしてください。

2. ランタイムエンベロープ — クエリの実行中にプロセス内ランタイムがスローします（packages/1-framework/1-core/framework-components/src/execution/runtime-error.ts の RuntimeErrorEnvelope を参照）：

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

category は PLAN | CONTRACT | LINT | BUDGET | RUNTIME のいずれかです（code のプレフィックスに対応します）。details には構造化されたコンテキストが格納されます（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 ドライバーエラーは通常、ユーザーに届く前にミドルウェアによってラップされますが、raw SQL の経路ではそのまま表面化することがあります。

ラップされたエラーと meta.code

一部のコマンドでは、下流のエラーを PN-RUN-3000（errorRuntime）エンベロープでラップし、元のコードを meta.code に格納します。最も重要な例は migrate です。migrate は、mapMigrationToolsError を介して MigrationToolsError（MIGRATION.HASH_MISMATCH、MIGRATION.STALE_CONTRACT_BOOKENDS、MIGRATION.AMBIGUOUS_TARGET などのコードを持ちます）をラップします。表示されるエンベロープは、code: 'PN-RUN-3000'、meta.code: 'MIGRATION.HASH_MISMATCH' となります。code が PN-RUN-3000 の場合は、必ず meta.code を確認してください。ルーティングに役立つ情報はそこにあります。

完全なエンベロープを確認する方法

ユーザーが人間向けの概要しか貼り付けていない場合は、--json の出力（機械可読なエンベロープ）を求めるか、-v を付けて再実行するよう依頼してください（CLI が構造化フィールドをすべて出力します）。--json と -v はすべての CLI コマンドで使えるグローバルフラグです。

ルーティング — スクリプトの終了処理とクローズ済みクライアント

これらの症状は PN-* エンベロープではありません。メッセージテキストをもとにルーティングし、prisma-next-runtime § スクリプトとしての実行（終了処理） に進んでください。

症状	次の対応
TypeError: db.end is not a function	ランタイムクライアントは db.end() を公開していません。これは node-postgres のプール API（pool.end()）です。正しくは await db.close() を呼び出します。prisma-next-runtime § スクリプトとしての実行（終了処理） を参照してください。
クエリ結果が出力された後にスクリプトがハングする／プロセスが終了しない	Postgres では、ファサードが所有する pg.Pool によりイベントループが終了しません。スクリプトの戻り値を返す前に await db.close() を呼び出すか、スクリプトモジュールの先頭で await using db = postgres<Contract>(...) を指定してください（リクエストハンドラー内に await using を置かないでください。ブロックスコープのため、リクエストごとにクローズされます）。prisma-next-runtime § スクリプトとしての実行（終了処理） を参照してください。
Error('Postgres client is closed') ／ Error('SQLite client is closed') ／ Error('Mongo client is closed')	クライアントは db.close() によりクローズされています（終端状態）。早すぎる close() を取り除くか、すべてのクエリの後に close() が最後に実行されるよう順序を変更するか、再接続する場合は新しい db を作成してください。prisma-next-runtime § スクリプトとしての実行（終了処理） を参照してください。

ルーティング — 症状とコード → 次の対応

信頼できる唯一の情報源です。エンベロープを読み、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.missingExtensions に記載されたディスクリプターを、prisma-next.config.ts の extensions に追加します。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（自己出力）または migrate	migration.ts を編集し、指定された placeholder("<slot>") を実際のクエリクロージャーに置き換えて、自己出力します。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 のコントラクトが一致しません	データ変換クエリプランの構築時	dataTransform(endContract, …) とクエリビルダーのコンテキストの両方に、同じ endContract の参照を渡します。
PN-RUN-3001 データベースに署名がありません	db verify、ランタイムの起動時	DB にマーカーがまだありません（空のベースライン DB の場合は）prisma-next db init --db <url>、（コントラクトを直接適用する場合は）db update --db <url> を実行します。
PN-RUN-3002 ハッシュが一致しません	db verify、ランタイムの起動時	マーカーとコントラクトのハッシュが一致しません。前方へマイグレーションするには migrate ／ db update を実行します。または、手動修正後に DB が正しい場合は 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 を参照）；MIGRATION.PATH_UNREACHABLE ／ MIGRATION.MARKER_MISMATCH（migrate --show --db $URL を実行してパスを確認し、続けて migration plan --from <from> --to <target> または migration list を実行してグラフを監査します。prisma-next-migration-review を参照）。
PN-SCHEMA-0001	db verify のスキーマチェック	ライブスキーマがコントラクトを満たしていません。差分は meta.verificationResult にあります。db update を実行するか、コントラクトを調整します。
MIGRATION.UP_TO_DATE ／ .DATABASE_BEHIND	migration status の info 診断	情報提供のみです。終了コードは 0 です。prisma-next-migration-review を参照してください。
MIGRATION.MISSING_INVARIANTS	migration status の info 診断	ライブマーカーは構造上、宛先のハッシュに到達していますが、ターゲット参照で必要とされるすべての不変条件を含んでいません。不足している不変条件をカバーするパスを通るには、migrate --to <name> --db $URL を実行します。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 ／明示的な列を追加）、または lint 設定を緩和します。prisma-next-runtime を参照してください。
PLAN.HASH_MISMATCH	コンパイル済みプランの実行時	プランの構築時に使用されたコントラクトとランタイムのコントラクトが一致しません。再出力、再ビルド、再デプロイしてください。
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- コードなし）	ドライバーエラーを返す raw SQL の処理	sqlState ＋ constraint ＋ table ＋ column を確認します。Postgres の 23505 は一意性違反、23503 は外部キー違反などです。データまたはスキーマを修正してください。
機能（例：型に returning() がない、多対多の読み込みから多対多リレーションの include を行う）に言及する TypeScript エラー	エンベロープが発生する前の作成時	機能ゲートは prisma-next.config.ts ではなく、コントラクト（ターゲット／ファミリーごとに名前空間化された capabilities ブロック）で宣言します。機能の宣言については prisma-next-contract に、どのメソッドがどの機能をゲートするかについては prisma-next-queries に問い合わせてください。有効化した後、再出力（pnpm prisma-next contract emit）します。
db.orm.<Model> のフィールド／メソッド不足、または古い Contract の形状に言及する TypeScript エラー	作成時	再出力（pnpm prisma-next contract emit）し、db.ts が postgres<Contract, TypeMaps>(...) でインスタンス化されていることを確認します（型パラメーターによってコントラクトの型が伝播します）。prisma-next-runtime と prisma-next-contract を参照してください。
エンベロープの code がこの表にない場合は、fix フィールドの指示に文字どおり従ってください。これはフレームワークが公式に示す次の手順です。fix が空、または役に立たない場合は、prisma-next-feedback を通じてエスカレーションしてください。

よくある落とし穴

1. summary だけを読み、エンベロープのほかのフィールドを読まないこと。 code、severity、why、fix、meta／details、（CLI エラーの場合は）where はすべて重要です。エージェントは code に基づいて処理を振り分け、ユーザーには summary が表示されます。
2. severity を無視すること。 migration status は警告レベルの診断を出力し、終了コード 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 でマーカーの実際の位置を確認できます。

Prisma Next がまだ対応していないこと

• Studio／GUI データベースブラウザー。 公式の Studio はありません。回避策：稼働中のスキーマを CLI のツリー形式で確認するには prisma-next db schema を使うか、サードパーティ製ツール（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 を通じて機能リクエストを提出してください。

エンベロープから次の手順がわからない場合の問い合わせ方法

1. -v（または機械可読な出力には --json）を付けて再実行し、エンベロープ全体を取得します。
2. エンベロープが本当に役に立たない場合（fix が空、meta がない、summary が汎用的など）は、フレームワークの機能不足です。エンベロープ、コントラクトのソース（機密情報を取り除いたもの）、再現手順を添えて 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 に問い合わせた。