Fix TypeScript TS5023: Unknown Compiler Option Error (2026)

The TypeScript compiler (tsc) is failing because it encountered an option in your tsconfig.json file that it doesn’t recognize.

Here’s what’s actually breaking: tsc is a state machine. It reads your configuration, builds an internal model of what you want it to do, and then executes. When it hits an unknown compiler option, it halts the state machine before it even starts processing your code, because it can’t build a valid execution plan. It’s like asking a chef to make a dish with an ingredient they’ve never heard of – they can’t proceed.

The most common causes, from most to least frequent:

1. Typo in the Compiler Option: You’ve simply misspelled an option. This is incredibly common.

   • Diagnosis: Visually inspect your tsconfig.json for common typos. Look for extra letters, missing letters, or swapped characters. For example, targett instead of target, or strictNullChecks instead of strictNullChecks.
   • Fix: Correct the spelling. If you intended target: "es2020", ensure it’s spelled exactly like that.
   • Why it works: tsc has a predefined list of valid compiler options. A typo means the option isn’t on that list, so correcting the spelling makes it recognizable.

2. Using a Deprecated or Removed Option: You’re using an option that was valid in an older version of TypeScript but has since been removed.

   • Diagnosis: Check the TypeScript release notes or documentation for the version you’re using. Search for the option listed in the error. For example, noEmitHelpers was removed.
   • Fix: Remove the deprecated option from your tsconfig.json. If its functionality is needed, find its modern equivalent. For noEmitHelpers, the modern approach is often to rely on module bundlers or specific import strategies.
   • Why it works: tsc no longer recognizes options that have been officially removed from its supported set.

3. Option Belongs to a Specific Plugin or Transformer: The option is not a built-in TypeScript compiler option but rather one provided by a third-party plugin (like typescript-eslint or a Babel plugin for TypeScript).

   • Diagnosis: Examine the problematic option. If it’s not in the official TypeScript handbook, it’s likely from a plugin. For instance, eslint might introduce options that tsc itself doesn’t understand if not properly configured.
   • Fix: Ensure the relevant plugin is installed and configured correctly. For eslint options, you’d typically configure them within your .eslintrc.js or .eslintrc.json file, not tsconfig.json. If it’s a transformer, make sure it’s listed in the plugins or transformers array of your tsconfig.json if the plugin requires it.
   • Why it works: tsc can be extended. Plugins register their options with the compiler. If the plugin isn’t installed or its registration process isn’t followed, tsc won’t know about its options.

4. Incorrect Case Sensitivity: While most tsconfig.json keys are case-insensitive in practice, some underlying parsers or configurations might be sensitive, or you might have a mix-up.

   • Diagnosis: Double-check the casing of your compiler options. Standard practice is camelCase, like strictNullChecks.
   • Fix: Ensure all compiler options follow the standard camelCase convention. For example, change STRICTNULLCHECKS to strictNullChecks.
   • Why it works: Although less common for standard options, strict parsing can occur, and adhering to convention avoids potential issues.

5. Using an Option from a Future TypeScript Version: You’ve copied a tsconfig.json from a project using a newer TypeScript version that includes options not present in your currently installed version.

   • Diagnosis: Compare the option in your tsconfig.json with the documentation for the exact version of TypeScript you have installed (tsc --version).
   • Fix: Either upgrade your TypeScript version to match the tsconfig.json (npm install typescript@latest or yarn add typescript@latest) or remove the unsupported option from your tsconfig.json.
   • Why it works: Each TypeScript version has a specific set of recognized compiler options. An option from a later version simply doesn’t exist in an earlier one.

6. Corrupted tsconfig.json File: The file itself might be malformed due to an incomplete save, copy-paste error, or encoding issues.

   • Diagnosis: Open tsconfig.json in a text editor. Look for syntax errors like missing commas, unclosed brackets, or invalid characters. Ensure the file is saved with UTF-8 encoding.
   • Fix: Correct the syntax errors or re-create the tsconfig.json file from scratch, carefully adding only known, valid options.
   • Why it works: tsc parses tsconfig.json as JSON. If the JSON is invalid, it can’t even read the options, leading to errors before it gets to option validation.

After fixing the unknown compiler option, the next error you’ll likely encounter is related to type checking or module resolution, as tsc can now attempt to process your code.