This TypeScript error occurs when tsconfig.json contains a compiler option that doesn't exist, is misspelled, or isn't supported by your current TypeScript version. The fix involves correcting typos, verifying option names against the official documentation, or upgrading TypeScript to access newer features.
The "Compiler option 'X' is not valid" error (TS5023) appears when TypeScript encounters an unrecognized configuration option in your tsconfig.json file. This happens when you specify a compiler option that either doesn't exist in TypeScript's configuration schema, is misspelled, or is only available in a newer version of TypeScript than the one you're currently using. TypeScript's compiler options are strictly validated against a known set of configuration keys. When you use an option name that doesn't match any valid option, the compiler immediately rejects it rather than silently ignoring it. This strict validation helps catch configuration mistakes early but can be frustrating when dealing with version compatibility or documentation that references newer features. Common scenarios include: 1. **Typos in option names**: Misspelling a valid option (e.g., "strictNullCheck" instead of "strictNullChecks") 2. **Version mismatches**: Using options from TypeScript 5.0+ in a TypeScript 4.x project 3. **Tool incompatibility**: Some build tools or executors (like ts-node) may not support all compiler options that are valid in tsc 4. **Deprecated options**: Using old option names that have been removed in newer TypeScript versions 5. **Wrong nesting level**: Placing root-level options under compilerOptions or vice versa
Read the error message carefully to find which option is causing the problem:
# Run TypeScript compiler to see the error
npx tsc
# Example error output:
# error TS5023: Unknown compiler option 'ignoreDeprecations'.
# error TS5023: Unknown compiler option 'moduleSuffixes'.The error message will explicitly name the problematic option. Make note of it for the next steps.
Open your tsconfig.json and verify the spelling of the flagged option:
// WRONG - common typos
{
"compilerOptions": {
"strictNullCheck": true, // Missing 's' at end
"moduleResolutions": "node", // Extra 's'
"esModuleInterOp": true, // Wrong capitalization
"allowSyntheticDefaultImport": true // Wrong word order
}
}// CORRECT - proper spelling
{
"compilerOptions": {
"strictNullChecks": true,
"moduleResolution": "node",
"esModuleInterop": true,
"allowSyntheticDefaultImports": true
}
}Use your IDE's autocomplete (Ctrl+Space in VS Code) when editing tsconfig.json to avoid typos. Most editors provide IntelliSense for valid compiler options.
Check the official TypeScript TSConfig reference to confirm the option is valid:
Visit the [TypeScript TSConfig Reference](https://www.typescriptlang.org/tsconfig) and search for your option name.
# Also check if the option shows up in tsc help
npx tsc --help | grep "optionName"
# Or list all valid compiler options
npx tsc --allIf the option doesn't appear in the documentation or help output, it may not exist. Common non-existent options developers try to use:
- strictNullCheck → should be strictNullChecks
- resolveJsonModules → should be resolveJsonModule
- moduleResolutions → should be moduleResolution
- allowSyntheticDefaultImport → should be allowSyntheticDefaultImports
Some compiler options only exist in newer TypeScript versions:
# Check your current TypeScript version
npx tsc --version
# Example output:
# Version 4.9.5Options that require TypeScript 5.0+:
- ignoreDeprecations (TS 5.0+)
- verbatimModuleSyntax (TS 5.0+)
- moduleResolution: "bundler" (TS 5.0+)
Options that require TypeScript 4.7+:
- moduleSuffixes (TS 4.7+)
- customConditions (TS 4.7+)
If you need these options, upgrade TypeScript:
# Upgrade to latest TypeScript
npm install --save-dev typescript@latest
# Or upgrade to a specific version
npm install --save-dev [email protected]
# Verify new version
npx tsc --versionAfter upgrading, restart your IDE's TypeScript server (in VS Code: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server").
Ensure options are at the correct nesting level. Some go in compilerOptions, others at the root:
// WRONG - mixing up placement
{
"compilerOptions": {
"include": ["src/**/*"], // ✗ Should be at root level
"exclude": ["node_modules"] // ✗ Should be at root level
}
}// CORRECT - proper structure
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"strict": true
},
"include": ["src/**/*"], // ✓ Root level
"exclude": ["node_modules"], // ✓ Root level
"references": [] // ✓ Root level
}Options that go in compilerOptions:
- target, module, lib, jsx, strict, etc.
Options that go at root level:
- include, exclude, files, extends, references, compileOnSave
Some build tools (ts-node, tsx, swc) don't support all TypeScript compiler options:
# If using ts-node and getting errors for valid options
# Check ts-node compatibility
# For example, ts-node may not support:
# - moduleSuffixes
# - customConditionsIf you encounter this, you have a few options:
Option 1: Use a different compiler option
// Instead of unsupported option, use alternative
{
"compilerOptions": {
// If moduleSuffixes not supported by ts-node
// Use paths mapping instead
"paths": {
"*": ["*.ios", "*"]
}
}
}Option 2: Use separate tsconfig files
// tsconfig.json (for development with ts-node)
{
"compilerOptions": {
// Only options ts-node supports
}
}
// tsconfig.build.json (for production builds)
{
"extends": "./tsconfig.json",
"compilerOptions": {
"moduleSuffixes": [".ios", ""] // Newer option for tsc
}
}Then build with: npx tsc -p tsconfig.build.json
If you can't resolve the issue, temporarily remove the option:
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
// "unknownOption": true, // Commented out until resolved
"strict": true
}
}After removing the option, test if your project still compiles:
npx tsc
# If successful, your build should complete without errorsResearch whether you actually need that option. Many compiler options are optional or have sensible defaults. Only add back options that are truly required for your use case.
### TypeScript Version-Specific Options
TypeScript regularly introduces new compiler options. Here's a timeline of notable additions:
TypeScript 5.0 (March 2023):
- verbatimModuleSyntax - Stricter import/export syntax checking
- ignoreDeprecations - Suppress deprecation warnings
- moduleResolution: "bundler" - Optimized for modern bundlers
TypeScript 4.7 (May 2022):
- moduleSuffixes - Platform-specific module resolution (.ios.ts, .native.ts)
- customConditions - Custom package.json export conditions
TypeScript 4.5 (November 2021):
- preserveValueImports - Keep imports that might be used at runtime
When copying configuration from online examples, always check which TypeScript version the example uses. A tsconfig from a TypeScript 5.0+ tutorial won't work with TypeScript 4.x.
### Deprecated and Removed Options
TypeScript occasionally deprecates options. Using these will cause errors in newer versions:
Removed in TypeScript 5.0:
- importsNotUsedAsValues → use verbatimModuleSyntax
- preserveValueImports → use verbatimModuleSyntax
If you're upgrading TypeScript and encounter errors about invalid options, check the [TypeScript Breaking Changes](https://github.com/microsoft/TypeScript/wiki/Breaking-Changes) documentation.
### Tool-Specific Limitations
ts-node doesn't support:
- moduleSuffixes (as of ts-node 10.9)
- Some experimental options
Solution: Use tsx (a faster, more compatible alternative to ts-node):
npm install -D tsx
# Run files with tsx instead of ts-node
npx tsx src/index.tsSWC (speedy-web-compiler) doesn't use all TypeScript compiler options since it doesn't do type checking. It ignores options like:
- strict
- noUnusedLocals
- Most type-checking flags
When using SWC, you still need to run tsc --noEmit separately for type checking.
### Validating tsconfig.json Schema
Modern IDEs provide schema validation for tsconfig.json. Ensure your editor is using the correct JSON schema:
VS Code automatically uses the TypeScript schema. If validation isn't working:
1. Check your VS Code settings include TypeScript
2. Install the TypeScript extension (usually bundled)
3. Verify the schema is associated with tsconfig.json files
You can also validate manually:
# Generate merged config to see what TypeScript actually uses
npx tsc --showConfig
# This shows the final configuration after extends, defaults, etc.### Extends and Option Inheritance
When using extends, child configs can override parent options, but can't use options the parent doesn't recognize:
// tsconfig.base.json (TypeScript 4.9)
{
"compilerOptions": {
"target": "ES2022"
}
}
// tsconfig.json (TypeScript 5.0)
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"verbatimModuleSyntax": true // ✓ OK, added in child
}
}But if the base config has an invalid option, extending it will fail:
// tsconfig.base.json
{
"compilerOptions": {
"unknownOption": true // ✗ Invalid
}
}
// tsconfig.json
{
"extends": "./tsconfig.base.json" // ✗ Fails due to parent's invalid option
}### Debugging Configuration Issues
Use these commands to debug tsconfig problems:
# Show final merged configuration
npx tsc --showConfig
# Show all available compiler options
npx tsc --all
# Show TypeScript help with valid options
npx tsc --help
# List files that will be compiled
npx tsc --listFiles | head -20For complex configurations with multiple extends and overrides, --showConfig is invaluable for understanding what TypeScript actually sees.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript