TypeScript "TS2688: Cannot find type definition file for" - Fix in CI

By Daniel Zoghalchali·Latchkey

Your compilerOptions.types (or a typeRoots entry) names a type package that is not installed. tsc looks for node_modules/@types/<name> (or the typeRoots path), does not find it, and raises TS2688 at config load.

What this error means

Type-checking fails before checking your code with error TS2688: Cannot find type definition file for '<x>'., naming the entry from your types array or typeRoots.

error TS2688: Cannot find type definition file for 'jest'.
  The file is in the program because:
    Entry point of type library 'jest' specified in compilerOptions

Diagnose it: which tsconfig and which compiler?

A TypeScript error that appears only in CI usually means the runner is compiling with a different config or a different compiler version than your editor. Your editor uses the workspace TypeScript and the nearest tsconfig.json; CI uses whatever the lockfile resolved and whatever config the build script names.

# what CI will actually use
npx tsc --version
npx tsc --showConfig | head -40

# which files are in the program (a missing include is a common cause)
npx tsc --listFiles | wc -l

# type-check only, no emit, same as most CI gates
npx tsc --noEmit

Common causes

types array names an uninstalled package

A compilerOptions.types: ["jest", "node"] allowlist names a package whose @types/* is not installed, so tsc cannot find its definition file.

typeRoots points at a missing path

A custom typeRoots entry references a directory that does not exist in CI (e.g. a local types folder not committed), so the named type cannot be located.

How to fix it

Install the named type packages

Add every package listed in types as a dev dependency.

npm install -D @types/jest @types/node

Fix or remove the types/typeRoots entry

Only list type packages you actually install, and point typeRoots at real paths.

// tsconfig.json
{ "compilerOptions": { "types": ["node", "vite/client"] } }

Pin the compiler so unrelated updates cannot break the gate

TypeScript adds errors in minor releases. An unpinned compiler turns a routine dependency update into a red build on code nobody touched, which is the most common false alarm in a TypeScript CI pipeline.

// package.json
{
  "devDependencies": {
    "typescript": "5.6.3"   // exact, not ^5.6.3
  }
}

How to prevent it

• Install @types/* for every entry in compilerOptions.types.
• Point typeRoots only at directories that exist in CI.
• Avoid an over-restrictive types allowlist you do not keep in sync.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation