JavaScript TypeError: Cannot read properties of undefined の原因と解決方法

TypeError: Cannot read properties of undefined とは

JavaScriptでTypeError: Cannot read properties of undefined (reading ‘xxx’)が発生するのは、undefinedまたはnullの値に対してプロパティアクセスやメソッド呼び出しを行った場合です。JavaScriptで最も頻繁に発生するランタイムエラーの一つであり、フロントエンド開発からNode.jsまで幅広い場面で遭遇します。

エラーの発生パターン

このエラーは主に以下のようなケースで発生します。

パターン1: ネストされたオブジェクトのプロパティアクセス

const user = {};
console.log(user.address.city);
// TypeError: Cannot read properties of undefined (reading 'city')

user.addressがundefinedのため、さらに.cityにアクセスするとエラーが発生します。

// 修正例1: オプショナルチェーン（ES2020）
console.log(user.address?.city);  // undefined（エラーにならない）

// 修正例2: 論理AND演算子
console.log(user.address && user.address.city);

// 修正例3: デフォルト値の設定
const city = user.address?.city ?? "不明";

パターン2: 配列の範囲外アクセス

const items = [{ name: "A" }];
console.log(items[5].name);
// TypeError: Cannot read properties of undefined (reading 'name')

// 修正例: インデックスの存在確認
if (items[5]) {
    console.log(items[5].name);
}
// または オプショナルチェーン
console.log(items[5]?.name);

パターン3: 非同期処理でのデータ未取得

// React の例
const [user, setUser] = useState();  // 初期値 undefined

// 初回レンダリング時にエラー
return <p>{user.name}</p>;
// TypeError: Cannot read properties of undefined (reading 'name')

// 修正例: 初期値の設定 + オプショナルチェーン
const [user, setUser] = useState(null);
return <p>{user?.name ?? "読み込み中..."}</p>;

根本原因の特定方法

このエラーをデバッグする際は、ブラウザの開発者ツール（DevTools）のConsoleタブでスタックトレースを確認します。エラーが発生した行で、ドット（.）やブラケット（[]）の左側の値がundefinedまたはnullになっています。

// デバッグ例
console.log(typeof user);        // "undefined" と表示されたら原因特定
console.log(user);               // undefined
console.log(JSON.stringify(user)); // "undefined"

防止策とベストプラクティス

このエラーを未然に防ぐには、以下のアプローチが有効です。オプショナルチェーン（?.）とNull合体演算子（??）はモダンJavaScriptの必須テクニックです。分割代入でのデフォルト値設定も効果的です。

// 防止策まとめ
// 1. オプショナルチェーン + Null合体演算子
const city = user?.address?.city ?? "デフォルト";

// 2. 分割代入でデフォルト値
const { address = {} } = user || {};
const { city = "不明" } = address;

// 3. Array.isArray() で配列チェック
if (Array.isArray(items) && items.length > 0) {
    console.log(items[0].name);
}

// 4. TypeScriptの厳密なnullチェック
// tsconfig.json: "strictNullChecks": true

Stack Overflowでの質問状況

Stack Overflowでは、JavaScriptに関する質問が非常に多く投稿されています。Cannot read properties of undefinedは最も質問数の多いエラーの一つであり、特にReact・Vue・Angular利用者からの質問が多いのが特徴です。

よくある質問（FAQ）