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.
const scores: number[] = [10, 20]; const third = scores[2]; // number | undefined with the option on
Try it
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.
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
{ "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
constand test it; repeatedarr[i]reads are not narrowed across statements the same way. - Loops with an index are the main pain point:
for (let i...) arr[i]yieldsT | undefined. Preferfor...oforentries(). - 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], index0and1are exact; index2is an error. Map.getalready returnsT | undefined, which is whyMapis often preferred toRecordfor lookups.- Pair it with
noPropertyAccessFromIndexSignatureto make index-signature access visibly different from normal properties. - Performance: none at runtime; this is purely a check.