How to fix 'noUncheckedIndexedAccess' requires 'strictNullChecks' in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 197 views

This TypeScript error occurs when you enable the 'noUncheckedIndexedAccess' compiler option without also enabling 'strictNullChecks'. The 'noUncheckedIndexedAccess' option adds 'undefined' to indexed property types, which only makes sense when TypeScript is strictly tracking null and undefined values. The fix is to either enable 'strictNullChecks' or disable 'noUncheckedIndexedAccess'.

Quick fix

Fixes 'noUncheckedIndexedAccess' requires 'strictNullChecks'

{
  "compilerOptions": {
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true
  }
}
  1. Enable strictNullChecks in tsconfig.json
  2. Disable noUncheckedIndexedAccess if you can't use strictNullChecks
  3. Check for conflicting tsconfig.json files
  4. Verify TypeScript version compatibility
typescript — error
{
  "compilerOptions": {
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true
  }
}
'noUncheckedIndexedAccess' requires 'strictNullChecks'

What this error means

The error "'noUncheckedIndexedAccess' requires 'strictNullChecks'" appears when you try to use TypeScript's `noUncheckedIndexedAccess` compiler option without having `strictNullChecks` enabled. This is a dependency requirement because `noUncheckedIndexedAccess` fundamentally changes how TypeScript handles indexed property access. `noUncheckedIndexedAccess` is a strictness option that adds `undefined` to the type of properties accessed via index signatures when those properties aren't explicitly declared. For example, with this option enabled, accessing `obj["dynamicKey"]` on an object with an index signature returns `string | undefined` instead of just `string`. This behavior only makes sense when TypeScript is tracking null and undefined values strictly via `strictNullChecks`. Without `strictNullChecks`, TypeScript treats `null` and `undefined` as assignable to any type, so adding `undefined` to indexed access types would have no effect and could lead to confusion. The TypeScript compiler enforces this dependency to ensure consistent type safety. If you want the stricter checking of `noUncheckedIndexedAccess`, you must first enable `strictNullChecks` to properly handle the potential `undefined` values it introduces.

Typical symptoms

  • TypeScript compilation fails with error: "'noUncheckedIndexedAccess' requires 'strictNullChecks'"
  • tsconfig.json has 'noUncheckedIndexedAccess': true but 'strictNullChecks': false or unspecified
  • Build process or IDE shows the error when compiling TypeScript code
  • Error appears after updating TypeScript version or modifying tsconfig.json
  • Project uses the 'strict' flag but someone manually disabled 'strictNullChecks'

Common causes

  1. tsconfig.json explicitly sets 'noUncheckedIndexedAccess': true without 'strictNullChecks': true
  2. Using 'noUncheckedIndexedAccess' as part of 'strict': true but someone overrode 'strictNullChecks' to false
  3. Inherited tsconfig.json from another project with incompatible compiler options
  4. TypeScript version upgrade changed default behavior or added new validation
  5. Build tool or framework configuration conflicts with tsconfig.json settings
  6. Multiple tsconfig.json files with conflicting compiler option values

How to fix "'noUncheckedIndexedAccess' requires 'strictNullChecks'"

1Enable strictNullChecks in tsconfig.json

The simplest fix is to enable strictNullChecks in your tsconfig.json file. This is required for noUncheckedIndexedAccess to work properly:

json
{
  "compilerOptions": {
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true
  }
}

If you're using the strict flag (which includes strictNullChecks), make sure it's enabled:

json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

After making this change, restart your TypeScript server in your IDE:
- VS Code: Press Cmd/Ctrl + Shift + P, then type "TypeScript: Restart TS Server"
- Other IDEs: Restart the IDE or rebuild the project

Test the fix by running:

bash
npx tsc --noEmit
2Disable noUncheckedIndexedAccess if you can't use strictNullChecks

If you cannot enable strictNullChecks (e.g., legacy codebase compatibility), disable noUncheckedIndexedAccess:

json
{
  "compilerOptions": {
    "strictNullChecks": false,
    "noUncheckedIndexedAccess": false
  }
}

Or remove the noUncheckedIndexedAccess option entirely (defaults to false):

json
{
  "compilerOptions": {
    "strictNullChecks": false
    // noUncheckedIndexedAccess is not specified (defaults to false)
  }
}

Note: Disabling noUncheckedIndexedAccess means TypeScript won't add undefined to indexed property accesses, which could hide potential runtime errors. Consider whether your project can migrate to strictNullChecks: true instead.

If you're using strict: true, you cannot disable strictNullChecks individually. The strict flag bundles multiple strictness options including strictNullChecks.

3Check for conflicting tsconfig.json files

TypeScript projects can have multiple tsconfig.json files (e.g., base config extended by others). Check all relevant files:

1. Look for extends:

json
{
  "extends": "./tsconfig.base.json"
}

2. Check the base file for strictNullChecks and noUncheckedIndexedAccess settings.

3. Look for tsconfig.json in parent directories - TypeScript searches up the directory tree.

4. **Check for tsconfig.*.json files** (e.g., tsconfig.build.json, tsconfig.test.json).

Example of resolving conflicts:

json
// tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

// tsconfig.json (extends base)
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    // No need to repeat - inherits from base
  }
}

If a child config overrides parent settings, ensure consistency:

json
// WRONG - child disables strictNullChecks while parent enables noUncheckedIndexedAccess
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "strictNullChecks": false  // Conflict!
  }
}
4Verify TypeScript version compatibility

The noUncheckedIndexedAccess option was introduced in TypeScript 4.1. Ensure you're using a compatible version:

bash
# Check TypeScript version
npx tsc --version

# Update TypeScript if needed
npm install typescript@latest --save-dev
# or for a specific version
npm install typescript@4.1 --save-dev

Version requirements:
- TypeScript 4.1+: noUncheckedIndexedAccess option available
- TypeScript 4.0+: strictNullChecks fully stable
- Older versions: Consider upgrading for better type safety

If you're using an older TypeScript version that doesn't support noUncheckedIndexedAccess, you'll get a different error. Update your package.json:

json
{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

After updating, delete node_modules and reinstall:

bash
rm -rf node_modules
npm install
5Handle build tool and framework configurations

Some build tools and frameworks have their own TypeScript configuration that might conflict:

Create React App (CRA):
CRA hides tsconfig.json. Eject or use react-scripts@5.0.0+ which includes TypeScript 4.x support.

Next.js:
Next.js has its own TypeScript configuration. Check next.config.js and ensure compatibility:

javascript
// next.config.js
module.exports = {
  typescript: {
    // Next.js ignores tsconfig.json errors by default in dev
    ignoreBuildErrors: false, // Set to true only for temporary workarounds
  }
}

Angular:
Angular uses tsconfig.json but may have additional constraints in angular.json:

json
{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "options": {
            "tsConfig": "tsconfig.app.json"
          }
        }
      }
    }
  }
}

Vite / Rollup / Webpack:
These tools use tsconfig.json directly. Ensure your build script references the correct config:

bash
# Example build command
npx tsc -p tsconfig.build.json

If using a monorepo (TurboRepo, Nx, Lerna), check each package's tsconfig.json for consistency.

6Migrate code to work with strictNullChecks

If you enable strictNullChecks, you may need to fix type errors in your code:

Common fixes for strictNullChecks errors:

1. Add null checks for potentially undefined values:

typescript
// Before: Error with strictNullChecks
const value = obj["key"]; // string | undefined
console.log(value.length); // Error: Object is possibly 'undefined'

// After: Add null check
const value = obj["key"];
if (value !== undefined) {
  console.log(value.length); // OK
}

2. Use optional chaining (?.):

typescript
const length = obj["key"]?.length; // number | undefined

3. Provide default values:

typescript
const value = obj["key"] ?? "default"; // string

4. Use type assertions when you're sure:

typescript
const value = obj["key"] as string; // Only if you're certain

5. Update function signatures:

typescript
// Before
function getName(id: string): string {
  return data[id]; // Might return undefined
}

// After
function getName(id: string): string | undefined {
  return data[id]; // Explicit return type
}

Run TypeScript in strict mode to find all issues:

bash
npx tsc --strict --noEmit

Consider incremental migration by enabling strictNullChecks in specific files first using // @ts-strict comments.

Advanced notes

### Understanding noUncheckedIndexedAccess

The noUncheckedIndexedAccess compiler option changes how TypeScript handles indexed property access on objects with index signatures:

Without noUncheckedIndexedAccess (default):

typescript
interface EnvironmentVars {
  NAME: string;
  OS: string;
  [propName: string]: string; // Index signature
}

declare const env: EnvironmentVars;
const nodeEnv = env.NODE_ENV; // Type: string (even though NODE_ENV isn't declared)

With noUncheckedIndexedAccess: true:

typescript
const nodeEnv = env.NODE_ENV; // Type: string | undefined

This option is particularly useful for:
- Configuration objects with dynamic keys
- Parsed JSON data
- Dictionary/map data structures
- Any object with an index signature

### Why strictNullChecks is Required

noUncheckedIndexedAccess adds undefined to indexed access types. Without strictNullChecks:
- undefined is assignable to any type
- The added undefined union would have no effect
- TypeScript would incorrectly assume values are never undefined
- The option would provide false sense of safety

### Migration Strategy for Large Codebases

If you have a large codebase without strictNullChecks:

1. Enable per file: Use // @ts-strict comments in individual files
2. Use skipLibCheck: Temporarily set skipLibCheck: true to ignore library type errors
3. Gradual rollout: Enable for new code first, migrate old code incrementally
4. TypeScript 5.0+: Use exactOptionalPropertyTypes for even stricter checking

### Performance Considerations

Enabling strictNullChecks and noUncheckedIndexedAccess:
- Slightly increases compilation time (more type checking)
- Improves runtime safety (catches potential errors)
- May require more explicit code (null checks, optional chaining)

For very large projects, measure compilation time impact and consider incremental builds.

### Framework-Specific Notes

React: With noUncheckedIndexedAccess, accessing dynamic object properties in state may require null checks:

typescript
const [data, setData] = useState<Record<string, string>>({});
const value = data["key"]; // string | undefined

Node.js: File system operations often return undefined for missing keys:

typescript
const env = process.env;
const apiKey = env["API_KEY"]; // string | undefined (with noUncheckedIndexedAccess)

Testing: Update test assertions to handle undefined cases:

typescript
expect(obj["key"]).toBeDefined(); // Instead of just checking value

### Alternative: Use Record Types

Instead of index signatures, consider using Record types with known keys:

typescript
// Instead of index signature
interface Config {
  [key: string]: string;
}

// Use Record with specific keys
type Config = Record<"apiUrl" | "timeout" | "retries", string>;

This provides better type safety without needing noUncheckedIndexedAccess.

Frequently asked questions

What does "'noUncheckedIndexedAccess' requires 'strictNullChecks'" mean?
The error "'noUncheckedIndexedAccess' requires 'strictNullChecks'" appears when you try to use TypeScript's noUncheckedIndexedAccess compiler option without having strictNullChecks enabled. This is a dependency requirement because noUncheckedIndexedAccess fundamentally changes how TypeScript handles indexed property access. noUncheckedIndexedAccess is a strictness option that adds undefined to the type of properties accessed via index signatures when those properties aren't explicitly declared.
How do I fix "'noUncheckedIndexedAccess' requires 'strictNullChecks'"?
This TypeScript error occurs when you enable the 'noUncheckedIndexedAccess' compiler option without also enabling 'strictNullChecks'. The 'noUncheckedIndexedAccess' option adds 'undefined' to indexed property types, which only makes sense when TypeScript is strictly tracking null and undefined values. The fix is to either enable 'strictNullChecks' or disable 'noUncheckedIndexedAccess'.
What causes "'noUncheckedIndexedAccess' requires 'strictNullChecks'"?
tsconfig.json explicitly sets 'noUncheckedIndexedAccess': true without 'strictNullChecks': true Using 'noUncheckedIndexedAccess' as part of 'strict': true but someone overrode 'strictNullChecks' to false Inherited tsconfig.json from another project with incompatible compiler options
Is the "'noUncheckedIndexedAccess' requires 'strictNullChecks'" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading