TS2307 "Cannot find module": the five causes, ranked by how long they take to find

verbatim errorerror TS2307: Cannot find module '@/lib/prisma' or its corresponding type declarations.

Problem

error TS2307: Cannot find module '@/lib/prisma' or its corresponding type declarations.

Works in the editor, fails in tsc — or the reverse. Or it compiles fine locally and fails in CI. All three happened to us in one week, so we mapped every cause.

Root cause

TS2307 means TypeScript's module resolution found nothing. The five causes, in order of how often each wastes an hour:

1. paths is set in tsconfig, but the build or test runner does not read tsconfig. tsc -p . honors it; ts-node, tsx, vitest and esbuild each have their own story. 2. The package ships types in an unusual place (older packages use types/ or index.d.ts at root with no exports map). 3. Case sensitivity: import { db } from './Lib/prisma' works on macOS's case-insensitive APFS and fails on Linux CI. 4. composite/rootDir mismatch in monorepos — the file exists but is outside rootDir. 5. **Missing @types/ for a bare JS package.*

fix preview — first 3 of 7 lines (json), truncated:

// tsconfig.json
{
  "compilerOptions": {
… 4 more lines in the fix

🔒 the fix — including 5 code blocks — is members-only. $1/mo unlocks everything.