noUncheckedIndexedAccess

What it is and why to use it

noUncheckedIndexedAccess adds undefined to reads whose indexed key is not known to exist. It helps reveal missing dictionary entries and out-of-bounds array reads. This option is not automatically enabled by strict, so a project must opt into it deliberately.

Common mistakes and limitations

The option changes checking, not runtime behaviour or data structures. A declared named property can remain definite, while an open index signature permits missing keys. Do not silence every warning with !; prove existence or handle absence.

Run this example

Use TypeScript 5.8 or later with strict checking and an ES2022 target. Save each complete example independently as example.ts, compile it, then run the generated JavaScript with a compatible Node.js installation. Compiler-only options below affect checking; they do not add runtime validation.

Terminal — compile and run

npx tsc example.ts --strict --target ES2022 --module commonjs
node example.js

Syntax

"noUncheckedIndexedAccess": true

Examples

Standalone TypeScript 5.8+ example; expected output is explained below.

const labels: Record<string, string> = { save: "Save" };
const actions = ["save"];
const action = actions[3];
console.log(action ?? "No action");
console.log(labels["cancel"] ?? "No label");

The fourth array position does not exist and evaluates to undefined.
The cancel dictionary entry is absent for the same runtime reason.
Both reads have explicit fallbacks. Compile this example with --noUncheckedIndexedAccess to make the compiler expose those missing-value possibilities.
Expected output: No action No label

Best practices

The option changes checking, not runtime behaviour or data structures. A declared named property can remain definite, while an open index signature permits missing keys. Do not silence every warning with !; prove existence or handle absence.
Keep external-input validation separate from compile-time type descriptions.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook