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'.

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).

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 ""TS5023: Unknown option""?