Debugging

Recipes for breaking into running Prisma code.

Sandbox + Chrome DevTools

The standard inner-loop debug experience:

cd sandbox
cp -r basic-sqlite my-repro && cd my-repro
pnpm install
pnpm dbpush
pnpm debug

Then in Chrome (or any Chromium browser), open chrome://inspect, click "Open dedicated dev tools for Node.js", switch to the Sources tab, and resume execution (F8). Add debugger; statements in source for breakpoints, or use the DevTools UI.

Pair with pnpm watch from the repo root for fast rebuilds while you debug.

Debugging the Prisma CLI

The CLI entry point is packages/cli/src/bin.ts. To run it directly without going through a sandbox:

cd packages/cli
./src/bin.ts -v          # prints version 0.0.0 in dev
./src/bin.ts generate    # invokes prisma generate

The bin.ts is executable (shebang line) and uses tsx under the hood. pnpm prisma -v from any sandbox project also works and is the canonical "is my dev setup linked properly" check.

Debugging Studio in isolation

From AGENTS.md:

For isolated Studio verification, you can run packages/cli/src/Studio.ts directly via pnpm exec tsx and pass a config object that preserves loadedFromFile; this keeps SQLite URLs resolving relative to the config file while avoiding unrelated packages/cli/src/bin.ts imports.

Studio is bundled into packages/cli/build/studio.js and packages/cli/build/studio.css; the server-side glue is in packages/cli/src/studio-server.ts. If a click or Enter doesn't open a cell editor, first verify the column is writable — views/system tables and read-only columns intentionally stay non-editable, so it's not always a regression.

Debug logging

Most Prisma packages use @prisma/debug (in packages/debug) which is a thin layer over debug. Enable it with:

DEBUG="prisma:*" prisma generate
DEBUG="prisma:client" node my-script.js
DEBUG="*" ...                # everything (verbose)

Each subsystem registers under a prisma:<area> namespace. Grep for Debug( calls in the package you're debugging to see what namespaces it uses.

Triggering panics in the engines

Sometimes you need to verify panic-handling pathways. From CONTRIBUTING.md, set one of these and run the corresponding command:

Variable	Triggered by
FORCE_PANIC_SCHEMA_ENGINE=1	npx prisma migrate dev
FORCE_PANIC_PRISMA_SCHEMA=1	npx prisma format
FORCE_PANIC_GET_DMMF=1	npx prisma validate
FORCE_PANIC_GET_CONFIG=1	npx prisma validate

Useful for testing error rendering paths in packages/internals and packages/migrate.

Custom engine builds

If you need a Wasm or Schema Engine binary built from a prisma-engines branch (or a local checkout):

1. Open packages/fetch-engine/package.json.
2. Add to enginesOverride either:
   • "branch": "<engines-branch>" — the script will git pull from prisma/prisma-engines and build it
   • "folder": "<absolute path to prisma-engines/target/release>" — use already-built artifacts
3. pnpm install to propagate.

For CI debugging on an open PR, add /engine-branch <branchName> to the PR body and re-run the pipeline. The engine from that branch is built before any tests run.

If you're making your own changes inside prisma-engines (assumed to be at $PRISMA_ENGINES_ROOT):

# Inside prisma-engines:
make build-schema-wasm
make build-qc-wasm

# Back inside prisma:
pnpm upgrade -r @prisma/prisma-schema-wasm@file:$PRISMA_ENGINES_ROOT/target/prisma-schema-wasm
pnpm upgrade -r @prisma/query-compiler-wasm@file:$PRISMA_ENGINES_ROOT/query-compiler/query-compiler-wasm/pkg
pnpm build

Build only what you need — schema-wasm if your change is PSL/DMMF only, qc-wasm if it's query planning only, both if you're not sure.

Reproducing user bug reports

The recommended pattern is the sandbox folder:

cd sandbox
cp -r basic-sqlite issue-29512 && cd issue-29512
# Edit prisma/schema.prisma and index.ts to match the bug report
pnpm install
pnpm dbpush
pnpm generate && pnpm start

If the issue requires a different provider, copy basic-sqlite and edit the schema's provider and the prisma.config.ts datasource. Other sandbox templates may exist — ls sandbox/ to check.

Common errors

• "Cannot find module @prisma/engines-version" — run pnpm install at the repo root, then pnpm dev to rebuild. The engines version is downloaded by packages/engines's install hook.
• pnpm prisma -v returns a non-zero version — your sandbox is using the npm version instead of the workspace one. Re-run pnpm install in the sandbox.
• Functional test types fail to resolve — type-only imports may need a pnpm install to refresh the workspace graph. From AGENTS.md: "Type-only imports from workspace packages work at runtime but IDE may show errors until pnpm install refreshes the workspace graph."