TypeScript "TS5023: Unknown compiler option" - Fix tsconfig in CI

By Daniel Zoghalchali·Latchkey

tsc does not recognize a compilerOptions key in your tsconfig. Either it is misspelled, it was removed/renamed, or it requires a newer TypeScript than CI has installed.

What this error means

tsc fails at config load with error TS5023: Unknown compiler option '<x>'. It happens before any type-checking, and reproduces consistently against that tsc version.

tsc output

error TS5023: Unknown compiler option 'moduleDetection'.
# or, version-related:
error TS5023: Unknown compiler option 'verbatimModuleSyntax'.

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.

Terminal

# 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

Typo or removed/renamed option

A misspelled key, or a flag that a TypeScript release removed or renamed (e.g. legacy options dropped in newer majors), is unknown to the compiler.

Option newer than the installed tsc

A modern option (verbatimModuleSyntax, moduleDetection, customConditions) is valid only on a newer TypeScript than CI installed, so an older tsc rejects it.

How to fix it

Align the TypeScript version with the options

Pin a tsc that supports every option your tsconfig uses, and verify the installed version.

Terminal

npm install -D typescript@latest
npx tsc --version   # confirm it supports the options in tsconfig.json

Fix the option name

Cross-check the key against the current tsconfig reference; correct any typo.
Remove options dropped in your TypeScript version.
Ensure CI installs the same TypeScript version as local (commit the lockfile).

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

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

How to prevent it

Pin TypeScript in devDependencies and install via npm ci.
Match tsconfig options to the installed TypeScript version.
Validate config locally with tsc --noEmit before pushing.

Frequently asked questions

What causes TypeScript "TS5023: unknown compiler option"?

There are 2 common causes: typo or removed/renamed option and option newer than the installed tsc. A misspelled key, or a flag that a TypeScript release removed or renamed (e.g.

How do I fix TypeScript "TS5023: unknown compiler option"?

There are 2 fixes depending on which cause you have: align the typescript version with the options and fix the option name. Work through them in order, since the first is the most common.

What does TypeScript "TS5023: unknown compiler option" actually mean?

tsc fails at config load with error TS5023: Unknown compiler option '<x>'.

How do I stop TypeScript "TS5023: unknown compiler option" happening again?

Pin TypeScript in devDependencies and install via npm ci. The prevention section lists 3 changes that keep it from recurring.