Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Type Checking Options

TypeScript noUncheckedIndexedAccess option

Reference for noUncheckedIndexedAccess: why array and record reads gain undefined, how to narrow them, and which accesses stay unchanged.

Reading list[5] from an array of three numbers gives undefined at runtime, yet TypeScript normally types the read as plain number. The same happens with index signatures such as Record<string, User>: any key looks present.

noUncheckedIndexedAccess closes that hole. With it on, every read through an index signature or array index has | undefined added to its type, so you must check before use. It is not part of strict, and many teams add it as one of the most useful extra checks.

TypeScript
const scores: number[] = [10, 20];
const third = scores[2]; // number | undefined with the option on

Try it

TypeScript Reads that may be undefined

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Safe patterns that need no cast

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

JSON
{ "compilerOptions": { "noUncheckedIndexedAccess": true } }
Part Description
Value true or false. Default: false. Not included in strict.
Affected reads arr[i], obj[key] through string or number index signatures, tuple access beyond the known length, and destructuring from arrays.
Not affected Known properties, tuple positions inside the length, for...of, map, forEach, and writes.
Error you will see TS18048: 'x' is possibly 'undefined'. or TS2532 / TS2345 when passing the value on.

Usage notes

  • Narrow once, reuse. Assign the read to a const and test it; repeated arr[i] reads are not narrowed across statements the same way.
  • Loops with an index are the main pain point: for (let i...) arr[i] yields T | undefined. Prefer for...of or entries().
  • The ! operator silences the error but reintroduces the risk; use it only where an invariant guarantees the element exists.
  • Tuples keep their precision. For [string, number], index 0 and 1 are exact; index 2 is an error.
  • Map.get already returns T | undefined, which is why Map is often preferred to Record for lookups.
  • Pair it with noPropertyAccessFromIndexSignature to make index-signature access visibly different from normal properties.
  • Performance: none at runtime; this is purely a check.