TypeScriptのpossibly undefinedエラーの直し方
TypeScript の error TS2532: Object is possibly 'undefined'. は、undefined になるかもしれない値のプロパティを、確かめずに読もうとしたときに出ます。配列の find で検索した結果や、users[0] のように番号で取り出した要素でよく出ます。if で undefined でないことを確かめるか、?. と ?? で「見つからなかったとき」の値を決めると、エラーは消えます。
検索結果が見つからないときの処理を書き忘れた、という実行時のバグを、型チェックの段階で知らせてくれるエラーです。私は検証環境で tsc とエディターが使う言語サーバーの両方でこのエラーを起こし、メッセージの全文と、直すと消えることを確かめました。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。TypeScript は 7.0.2 を使い、比べるために 5.9.3 と 6.0.3 でも同じファイルを tsc にかけました。エディターの表示は、VS Code などのエディター本体ではなく、エディターが診断に使う TypeScript の言語サーバー(tsc --lsp --stdio)を直接動かして確かめました。VS Code の画面での見え方、React などのフレームワークの中で出る場合は試していません。
エラーの全文
検証環境で、空のフォルダーに TypeScript 7.0.2 を入れ、npx tsc --init で tsconfig.json を作りました。できた tsconfig.json には "strict": true と "noUncheckedIndexedAccess": true が入っていました。
src/find.ts に、ユーザーの配列から id が 3 の人を find で探し、その名前を表示するコードを書きました。
type User = { id: number; name: string };
const users: User[] = [
{ id: 1, name: "Alice" },
{ id: 2, name: "Bob" },
];
console.log(users.find((u) => u.id === 3).name);
npx tsc --noEmit を実行すると、次のように出ました(終了コードは1)。src には、このあとで出てくるほかの3つのファイルも置いていたので、実際にはエラーが4行出ています。ここでは src/find.ts の1行だけを載せます。
src/find.ts(8,13): error TS2532: Object is possibly 'undefined'.
--pretty を付けると、どこが問題なのかが波線で示されます(色を付けるための制御文字は消し、ほかのファイルの分と最後の集計は省いています)。
src/find.ts:8:13 - error TS2532: Object is possibly 'undefined'.
8 console.log(users.find((u) => u.id === 3).name);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
「そのオブジェクトは undefined かもしれない」という意味です。波線は .name ではなく、その手前の users.find((u) => u.id === 3) に引かれています。undefined かもしれないのは find の結果のほうだ、ということです。
find は、条件に合う要素がなければ undefined を返します(MDN の Array.prototype.find() の説明(英語))。TypeScript でも find の戻り値は User | undefined 型です。strictNullChecks の説明にあるとおり、このオプションが有効だと、undefined かもしれない値をそのまま使うとエラーになります。strictNullChecks は strict に含まれるので、"strict": true のプロジェクトではこのエラーが出ます。
エディターでも同じエラーが出る
エディターは、TypeScript の言語サーバーから診断(エラーの位置とメッセージ)を受け取って、赤い波線を引きます。TypeScript 7.0.2 の言語サーバーを tsc --lsp --stdio で起動し、エディターと同じ手順で src/find.ts を開かせると、次の診断が返ってきました。返ってきた JSON を、私が書いた小さなスクリプトで1件1行に整えて表示しています(ホバーの行は省いています)。
server: typescript-go 7.0.2
diagnostics (1):
8:13-8:42 severity=1 source=ts code=2532 Object is possibly 'undefined'.
8:13-8:42 は、8行目の13文字目から、42文字目(.name の .)の手前までで、tsc --pretty の波線と同じ範囲です。severity=1 はエラー、code=2532 は TS2532 のことです。メッセージの文面も tsc と同じでした。
変数に入れると TS18048 に変わる
find の結果をいったん変数に入れてから使うと、エラーの番号と文面が変わります。
const user = users.find((u) => u.id === 3);
console.log(user.name);
src/find-var.ts(9,13): error TS18048: 'user' is possibly 'undefined'.
TS2532 では「Object」だった部分に、変数の名前 'user' が入りました。言語サーバーで user にカーソルを合わせたときの表示(ホバー)は const user: User | undefined でした。省略できるプロパティでも同じです。type Config = { db?: { host: string } }; の db のように ? を付けたプロパティを、確かめずに config.db.host とたどると、'config.db' is possibly 'undefined'. のように、たどったプロパティの名前まで入った TS18048 になりました。
検証した4つの書き方で出たエラーをまとめると、次のとおりです。TS2532 と TS18048 は、どちらも同じ理由で出るエラーで、直し方も同じです。
| 書き方 | 出たエラー |
|---|---|
users.find(...).name |
TS2532: Object is possibly 'undefined'. |
users[0].name |
TS2532: Object is possibly 'undefined'. |
const user = users.find(...) のあと user.name |
TS18048: 'user' is possibly 'undefined'. |
config.db.host(db は省略できるプロパティ) |
TS18048: 'config.db' is possibly 'undefined'. |
TypeScript 5.9.3 と 6.0.3 でも、同じファイルで同じ番号と文面のエラーが出ました。ただし tsc の終了コードは、5.9.3 と 6.0.3 では 2、7.0.2 では 1 でした。CI などで終了コードの値そのものを見ている場合は、気をつけてください。
users[0] で出るのは noUncheckedIndexedAccess のため
users[0].name でも TS2532 が出ました。配列の要素を番号で取り出したときに undefined を足すのは、noUncheckedIndexedAccess というオプションです。TypeScript 7.0.2 の tsc --init で作った tsconfig.json では、これが true になっていました。
同じファイルで --noUncheckedIndexedAccess false を付けて tsc を実行すると、users[0].name のエラーだけが消え、find と config.db のエラーは残りました。find の結果に undefined が付くのは、noUncheckedIndexedAccess とは関係なく、strictNullChecks によるものだからです。strictNullChecks も無効にすると、4つともエラーは出なくなりました。このとき、tsc --init の設定に入っている exactOptionalPropertyTypes は、strictNullChecks なしでは指定できず TS5052 のエラーになったので、これも無効にしました。
確かめずに実行すると TypeError で止まる
型のエラーは、実行時に起きることを先に知らせているだけです。src/find.ts を Node.js 22.23.4 でそのまま実行すると(Node.js は型の注釈を取り除いて実行するだけで、型チェックはしません。Node.js の TypeScript の説明)、次のように止まりました(終了コードは1。パスは例示用の値に置き換え、スタックの残りは省いています)。
/path/to/app/src/find.ts:8
console.log(users.find((u) => u.id === 3).name);
^
TypeError: Cannot read properties of undefined (reading 'name')
at Object.<anonymous> (/path/to/app/src/find.ts:8:42)
id が 3 のユーザーがいないので find が undefined を返し、その .name を読もうとして止まっています。TS2532 は、このエラーを実行する前に知らせてくれていたわけです。
直し方とエラーが消えたこと
直したファイルに入れ替えて npx tsc --noEmit を実行すると、何も表示されずに終了コード 0 で終わりました。言語サーバーに開かせても、どのファイルも diagnostics (0): で、エラーは返ってきませんでした。
if で undefined でないことを確かめる
見つからなかったときに別の処理をしたいなら、if で分けます。
const user = users.find((u) => u.id === 3);
if (user === undefined) {
console.log("id 3 のユーザーはいません");
} else {
console.log(user.name);
}
if で確かめたあとは、TypeScript が user の型を絞り込みます(公式ハンドブックの、=== による型の絞り込みの説明)。言語サーバーのホバーで見ると、if (user === undefined) の行の user は User | undefined ですが、else の中の user は User になっていました。実行すると「id 3 のユーザーはいません」と表示されました。
users[0] のときも、いったん変数に入れて if (first) で確かめるとエラーは消えました。配列のすべての要素を順に使うだけなら、for (const user of users) で回せば確かめる必要はありません。ホバーで見ると user の型は User で、エラーは出ませんでした。
?. と ?? で見つからなかったときの値を決める
表示するだけなど、見つからなければ代わりの値で済むときは、?.(オプショナルチェーン)と ?? を使うと1行で書けます(TypeScript 3.7 のリリースノート)。
console.log(users.find((u) => u.id === 3)?.name ?? "(見つかりません)");
?. は、手前の値が undefined か null なら、その先を読まずに undefined を返します。?? は、左が undefined か null なら右の値を使います。実行すると「(見つかりません)」と表示されました。省略できるプロパティの config.db.host も、config.db?.host ?? "localhost" にするとエラーが消え、localhost と表示されました。
見つからないのがおかしいなら例外を投げる
必ずあるはずのデータが見つからないのは、プログラムの誤りです。その場合は、見つからなかったらその場で例外を投げる関数にまとめると、呼び出す側では undefined を気にせずに済みます。
function getUser(id: number): User {
const user = users.find((u) => u.id === id);
if (!user) {
throw new Error(`id ${id} のユーザーが見つかりません`);
}
return user;
}
console.log(getUser(2).name);
if のあとの return user; では、user は User 型に絞り込まれているので、戻り値の型 User と合います。実行すると Bob と表示されました。
! でエラーを消すと、実行時に止まる
find(...)!.name のように ! を付けても、TS2532 は消えます。tsc も言語サーバーも、エラーを出しませんでした。
console.log(users.find((u) => u.id === 3)!.name);
! は「この値は undefined ではない」と TypeScript に伝えるだけで、実行時の動きは変わりません(公式ハンドブックの、! 演算子の説明)。このファイルを実行すると、直す前と同じ TypeError: Cannot read properties of undefined (reading 'name') で止まりました。! を使うのは、undefined にならないと分かっているときだけにします。
Node.js がこのファイルを実行したときのエラー表示では、8行目は console.log(users.find((u) => u.id === 3) .name); となっていて、! があった場所が空白になっていました。! は型のための書き方なので、Node.js が実行する前に空白に置き換えて取り除いています(Node.js の型の除去の説明)。





