TL;DR: Never use a global Prisma CLI for project work. Check prisma --version against the version pinned in package.json, switch to the project-local CLI via npx, and regenerate the migration. Pin the version in CI too, so the agent's sandbox cannot silently substitute a newer engine.

```text
agent's local prisma CLI is 5.x but the project pins 4.x - migrate diff generated SQL the old engine cant run
```

1. Detect the skew. Compare the CLI you actually invoked against the project's pinned version.
```
prisma --version
# and in the repo:
npx prisma --version
# compare both against the prisma version in package.json devDependencies
```
Expected: the global (or PATH-first) CLI reports 5.x while the project pins 4.x - or vice versa. You now know which binary produced the bad SQL.

2. Stop using the global CLI. Remove it from the equation: use npx prisma (which resolves the project-local install) for every Prisma command, and check that no global install shadows it on PATH.
Expected: npx prisma --version reports the pinned 4.x version from inside the repo.

3. Regenerate the migration SQL with the pinned CLI.
```
npx prisma migrate diff --from-schema-datamodel ... --to-schema-datamodel ... --script
```
Expected: the regenerated SQL uses only features the 4.x engine supports.

4. Verify the SQL against the project's engine version, ideally by applying it to a scratch database with the pinned CLI.
Expected: the migration applies cleanly under the version the project actually runs.

5. Pin it in CI and in the agent runbook: prisma commands run via npx from the repo, and the CI image installs the pinned version, never latest.
Expected: a fresh sandbox reproduces the pinned version with no manual steps.

## Use this when
- migrate diff generated SQL the project's Prisma engine cannot run
- The agent's global prisma CLI version differs from the project's pinned version
- A migration works on the agent's machine but fails in CI or production
- You see engine errors referencing SQL features your Prisma version should not emit

## Not for this skill when
- Both CLIs are the same version and the SQL still fails - that is a schema or database problem, not version skew
- The project intentionally uses the global CLI and pins nothing - then standardize on one version deliberately instead
- The error is a connection or permissions problem - version skew does not cause those
- You are mid-upgrade to Prisma 5 on purpose - then upgrade the project, the engine, and the runbook together

## Variant phrasings
- prisma CLI version mismatch migrate diff wrong SQL
- global prisma 5 vs project prisma 4 migration fails
- npx prisma vs global prisma different versions
- prisma migrate diff generated SQL old engine cant run

## Why it happens
migrate diff output is produced by the schema engine bundled with the CLI you invoke, not by the version in package.json. A 5.x CLI happily emits SQL using engine features the project's 4.x runtime does not understand, and nothing warns you at generation time - the failure surfaces later when the pinned engine tries to run it. Agents are especially prone to this because sandboxes often have a global CLI on PATH that shadows the project's local install.

## Edge cases
- pnpm and yarn PnP layouts resolve npx differently. Verify which binary actually runs with a version check in the repo, not by assumption.
- A globally installed CLI can also shadow in CI if the image pre-installs Prisma. Pin the install step to the package.json version.
- Regenerating with the old CLI can produce different SQL than the 5.x output - review the new migration file; do not just swap the header.
- If the team is mid-upgrade, keep a brief note of which migrations were generated under which version until the upgrade completes.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xzO7tz9EF8l7EA-FfUP0SA