JavaScript Uncaught TypeError: Cannot read properties of null/undefined の原因と解決方法【フレームワーク別実践ガイド】

Uncaught TypeError: Cannot read properties of null (reading ‘property’) または Uncaught TypeError: Cannot read properties of undefined (reading ‘property’) とは

JavaScript開発で頻繁に遭遇する「Uncaught TypeError: Cannot read properties of null (reading ‘property’)」や「Uncaught TypeError: Cannot read properties of undefined (reading ‘property’)」エラー。これは、存在しない（nullまたはundefined）オブジェクトや値に対してプロパティやメソッドにアクセスしようとした際に発生します。特に非同期処理やDOM操作、API連携が絡むと原因の特定が難しく、多くのエンジニアが頭を悩ませるポイントです。

エラーの発生パターン

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

パターン1: DOM要素が取得できていない状態でプロパティにアクセス

```javascript
// HTMLに 'myButton' というIDの要素が存在しない、またはスクリプト実行時にまだDOMにない場合
const myButton = document.getElementById('myButton');
// myButton は null になる
myButton.addEventListener('click', () => {
  console.log('Button clicked!');
});
```

このパターンは、`document.getElementById` や `document.querySelector` などでDOM要素を取得しようとしたものの、該当する要素が見つからなかった場合に発生します。取得結果が `null` となり、その `null` に対して `addEventListener` メソッドを呼び出そうとしてエラーになります。特にスクリプトの読み込み順序やDOMContentLoadedイベントを考慮しない場合に起こりやすいです。

```javascript
// DOM要素の存在を確認してから処理を実行する
const myButton = document.getElementById('myButton');
if (myButton) { // myButton が null でないことを確認
  myButton.addEventListener('click', () => {
    console.log('Button clicked!');
  });
} else {
  console.error('ID "myButton" の要素が見つかりません。');
}

// または、よりモダンなOptional Chainingを使用
// myButton?.addEventListener('click', () => {
//   console.log('Button clicked!');
// });
```

パターン2: APIレスポンスのデータ構造が期待と異なる

```javascript
// APIレスポンスのデータ構造が想定と異なる場合
async function fetchData() {
  const response = await fetch('/api/data');
  const data = await response.json();
  // data が { user: null } や { user: undefined }、または { } の場合
  console.log(data.user.name); // data.user が null/undefined のためエラー
}
fetchData();
```

APIからのレスポンスデータは、ネットワーク状況やサーバー側の都合で期待通りの構造になっていないことがあります。例えば、`user` プロパティが存在しない、あるいはその値が `null` や `undefined` であるにも関わらず、その内部の `name` プロパティにアクセスしようとするとこのエラーが発生します。特にネストされたオブジェクトのプロパティにアクセスする際に注意が必要です。

```javascript
// APIレスポンスのプロパティを安全にチェックしてからアクセスする
async function fetchData() {
  const response = await fetch('/api/data');
  const data = await response.json();

  // オプショナルチェーン (?.) を使用して安全にアクセス
  console.log(data.user?.name);

  // または、if文で存在チェック
  if (data && data.user && data.user.name) {
    console.log(data.user.name);
  } else {
    console.warn('ユーザー情報またはユーザー名がありません。');
  }
}
fetchData();
```

パターン3: 非同期処理の完了前にデータにアクセス

```javascript
let userData;

async function loadUserData() {
  // サーバーからデータをフェッチ（非同期処理）
  const response = await fetch('/api/user');
  userData = await response.json();
}

loadUserData();
// 非同期処理が完了する前に userData.name にアクセスしようとしている
console.log(userData.name); // userData は undefined のためエラー
```

JavaScriptの非同期処理（`fetch`、`setTimeout`、Promiseなど）では、処理の完了を待たずに次のコードが実行されることがあります。この場合、非同期処理で値がセットされるはずの変数が、アクセス時点ではまだ初期値（`undefined`）のままであり、そのプロパティにアクセスしようとするとエラーが発生します。特にグローバル変数やコンポーネントの状態を非同期で更新する際に注意が必要です。

```javascript
let userData;

async function loadUserData() {
  const response = await fetch('/api/user');
  userData = await response.json();
  // データがロードされた後にアクセスする
  console.log(userData.name);
}

loadUserData();
// もし外部からアクセスする必要があるなら、非同期処理完了を待つか、コールバックを使用する
// loadUserData().then(() => {
//   if (userData) {
//     console.log(userData.name);
//   }
// });
```

根本原因の特定方法

このエラーのデバッグには、{marker}エラーが発生している行の直前で問題の変数を `console.log()` で出力し、その値を確認する{/marker}のが最も効果的です。ブラウザの開発者ツールでブレークポイントを設定し、ステップ実行しながら変数の値を追跡することも非常に有効です。特に、`null` なのか `undefined` なのか、または期待するオブジェクトとは全く異なる値が入っているのかを確認することが重要です。

```javascript
// エラーが発生しそうな箇所の直前で変数を出力
let possiblyNullOrUndefinedObject = null; // 例として null

console.log('--- Debugging Start ---');
console.log('Value of possiblyNullOrUndefinedObject:', possiblyNullOrUndefinedObject);
console.log('Type of possiblyNullOrUndefinedObject:', typeof possiblyNullOrUndefinedObject);
console.log('--- Debugging End ---');

// ここでエラーが発生
// console.log(possiblyNullOrUndefinedObject.someProperty);
```

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

このエラーを予防するには、{marker}プロパティにアクセスする前に値が `null` または `undefined` でないことを確認{/marker}することが最も重要です。オプショナルチェーン (`?.`)、Nullish coalescing (`??`)、条件分岐（`if`文）、またはデフォルト値を設定するなどの方法があります。特に非同期処理の結果や、外部からの入力値に対しては常に存在チェックを行う習慣をつけましょう。

```javascript
// オプショナルチェーンによる予防
const user = null;
console.log(user?.name); // undefined を出力。エラーは発生しない。

// Nullish coalescing (??) による予防（null または undefined の場合にのみデフォルト値を適用）
const settings = { theme: 'dark' };
const layout = settings.layout ?? 'default'; // settings.layout が undefined なので 'default'
console.log(layout); // 'default'

// 論理OR (||) による予防（falsy値全般に適用される）
const count = 0;
const displayCount = count || 100; // count が 0 (falsy) なので 100
console.log(displayCount); // 100

// if文による予防
const data = {}; // 空のオブジェクト
if (data && data.items && Array.isArray(data.items)) {
  data.items.map(item => item);
} else {
  console.log('データが不正、または items が配列ではありません。');
}
```

よくある質問（FAQ）

この用語と一緒に知っておきたい用語