typescript config_error ai_generated true

error TS5023: Unknown compiler option 'X'.

ID: typescript/ts5023-unknown-compiler-option

Also available as: JSON · Markdown
95%Fix Rate
93%Confidence
45Evidence
2018-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
5 active — — —

Root Cause

Almost always caused by a mismatch between the tsconfig options and the installed TypeScript version. The option either does not exist yet in the user's version or was renamed/removed.

generic

Workarounds

  1. 95% success Check installed TS version and use version-appropriate options 
    Run 'npx tsc --version' to check the installed version. Consult the TypeScript release notes for when the option was introduced. Common mappings: verbatimModuleSyntax requires >=5.0, moduleDetection requires >=4.7, allowImportingTsExtensions requires >=5.0.

    Sources: https://www.typescriptlang.org/docs/handbook/release-notes/overview.html

  2. 88% success Replace the unknown option with its predecessor 
    verbatimModuleSyntax replaces isolatedModules + importsNotUsedAsValues. moduleDetection replaces heuristics from the module option. Remove the unknown option and use the older equivalent for your TS version.
  3. 92% success Use extends with a version-matched base tsconfig 
    Install a base config package: 'npm install -D @tsconfig/node20' then add '"extends": "@tsconfig/node20/tsconfig.json"' to your tsconfig.json. These base configs only use options valid for the target environment.

    Sources: https://github.com/tsconfig/bases

Dead Ends

Common approaches that don't work:

  1. Downgrading TypeScript to make the unknown option valid 72% fail

    Downgrading introduces incompatibilities with the rest of the codebase and dependencies that may require newer TS features. The option may have been removed entirely, so no version makes it valid.

  2. Copying tsconfig.json from a tutorial without checking TS version 85% fail

    Tutorial configs often use bleeding-edge options like verbatimModuleSyntax (TS 5.0+), moduleDetection (TS 4.7+), or allowImportingTsExtensions (TS 5.0+). The option does not exist in the installed version.

  3. Adding skipLibCheck or @ts-ignore to suppress the error 95% fail

    TS5023 is a config-level parse error, not a type error in source code. skipLibCheck and @ts-ignore only suppress type-checking errors. Config errors cannot be suppressed.

Error Chain

Frequently confused with: