Debugging Prisma & Common Failures Diagnose the failing layer instead of replacing the project
Course rule: Prisma CLI, @prisma/client and @prisma/adapter-pg are locked to 7.9.1. Newer Prisma releases are not substituted halfway through the course.
1. Debug Prisma by Layer Working directory / local package
2. Wrong Version or Global CLI Use the project-local CLI
pnpm exec prisma versionIf versions differ from 7.9.1, inspect package.json and the lockfile. Do not "fix" the docs to match a newer package accidentally installed.
3. Generated Client Module Error Symptoms may mention exports, require, ESM or module scope. In this NestJS CommonJS course, confirm the generator contains moduleFormat = "cjs" and regenerate the client. Regenerate after generator changes
pnpm exec prisma generate4. PrismaClient Requires an Adapter Prisma 7 direct database connections require a driver adapter. If the code constructs PrismaClient without PrismaPg, fix the construction path instead of downgrading packages.
5. DATABASE_URL vs DIRECT_URL Confusion Symptom Likely layer
migrate/status fails but API query works DIRECT_URL / Prisma CLI path
6. Shadow Database Failure If migrate dev reports permission denied to create database, verify the migration user privileges. If automatic creation is not allowed, configure a dedicated shadow database. Never reuse the development database as the shadow target.
7. Pooled Connection Mistakes Transaction pooling is optimized for different workloads and does not preserve all session behavior migration tools expect. Use a direct or session-capable connection for Prisma CLI migration workflows.
8. Schema Changed but TypeScript Did Not The generated client is stale. Run prisma generate and rebuild. Schema changes do not magically rewrite TypeScript imports already produced on disk.
9. "Relation Does Not Exist" Check migration status and target database/schema. A perfectly typed generated client can still point at a database where the migration was never applied.
10. Common Anti-Patterns • Creating new PrismaClient instances in controller methods.
• Putting DATABASE_URL into NEXT_PUBLIC_* variables.
• Using migrate dev in production.
• Ignoring migration SQL without review.
• Using db push to avoid learning migrations in a production-style project.
• Deleting the migrations directory whenever drift appears.
• Mixing Prisma 8 docs into this locked 7.9.1 course.
• Treating Prisma validation as authorization or business validation.
Checkpoint When a Prisma failure appears, identify whether it is tooling, generated code, adapter/runtime, network, privilege or database state before changing anything.
Prisma improves developer ergonomics, but migrations and generated queries still change a real relational database. You should be able to inspect both sides.
Restate the goal of “Debugging Prisma and Common Failures” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: domain intent → Prisma Client → generated SQL → PostgreSQL → mapped result. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: Prisma schema + migration history + generated client + NestJS PrismaService connected to TaskFlow PostgreSQL.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
const tasks = await prisma.task.findMany({
where: { workspaceId },
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
take: 20,
});Do not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Verify connection string, host, port, SSL/pooler mode, network reachability, and which environment file the process loaded.
Read the generated SQL before applying it and compare the change against existing production-shaped data.
Without copying the final source, create a second small scenario that applies “Debugging Prisma and Common Failures” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Model one entity, create the first migration, and inspect the SQL before applying it.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.CLI/client version mismatch
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.