Reactでundefinedをmapしてエラーになるときの直し方

​​React​TypeScript,Vite,トラブルシュート

React で Cannot read properties of undefined (reading 'map') というエラーが出るのは、map を呼んだ値がまだ配列ではなく undefined だったためです。API から取ってくる記事や商品の一覧を useEffect と fetch で取得して表示するとき、useState に初期値を渡していないと、データが届く前の最初の表示でこのエラーになります。useState<Post[]>([]) のように初期値を空の配列にするか、undefined の間は「読み込み中…」を返すようにすると、エラーは消えます。

私は検証環境でこのエラーをわざと起こし、ブラウザーのコンソールに出た文と、直したあとに消えることを確かめました。API の応答のキーを取り違えたときにも、同じ文のエラーが、今度はデータが届いたあとに出ました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。npm create vite@latest の react-ts テンプレートで作ったプロジェクト(react / react-dom 19.3.1、Vite 8.3.8、TypeScript 7.0.2、oxlint 1.93.0)で、コンポーネントを StrictMode で囲んで試しました。API の代わりに public/api/ に置いた JSON ファイルを fetch で取り、届く前の画面を見るために、応答を Playwright 1.63.0 で 1 秒遅らせました。ブラウザーは Chromium 153 です。Next.js などのフレームワークや、TanStack Query のようなデータ取得のライブラリを使った場合、Chromium 以外のブラウザーでの表示は試していません。

初期値なしの useState で出たメッセージ

次のコンポーネントは、記事の一覧を /api/posts.json から取ってきて <li> に並べます。useState に初期値を渡していないので、取得が終わるまで posts は undefined です。

tsx
// まちがい:初期値がないので、取得が終わるまで posts は undefined
import { useEffect, useState } from 'react';
import type { Post } from './types.ts';

export default function PostList() {
  const [posts, setPosts] = useState<Post[]>();

  useEffect(() => {
    fetch('/api/posts.json')
      .then((res) => res.json())
      .then((data: Post[]) => setPosts(data));
  }, []);

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Post は { id: number; title: string } の型です。このコンポーネントを開発サーバー(npm run dev と同じ vite)で開くと、すぐにエラーになりました。DevTools のコンソールに出たエラーは、次のとおりです。

text
Uncaught TypeError: Cannot read properties of undefined (reading 'map')
    at PostList (BadNoInitial.tsx:16:14)

TypeError は React ではなく JavaScript のエラーで(MDN のこのエラーの解説)、「undefined の map というプロパティを読もうとした」という意味です。at PostList のあとのファイル名と行番号(BadNoInitial.tsx:16)は、{posts.map((post) => ( の行を指していました。どのコンポーネントの、どの map が原因かは、ここから分かります。

エラーに続いて、警告も1件出ました。

text
An error occurred in the <PostList> component.

Consider adding an error boundary to your tree to customize error handling behavior.
Visit https://react.dev/link/error-boundaries to learn more about error boundaries.

ページのほうには、エラーの文は出ませんでした。コンポーネントを入れる <div id="root"> の中は、開いて 0.3 秒後も 2 秒後も空のままで、画面は真っ白です。

DevTools のコンソールに、赤い行で「Uncaught TypeError: Cannot read properties of undefined (reading 'map') at PostList (BadNoInitial.tsx:16:14)」、黄色い行で「An error occurred in the <PostList> component.」が出ている。上のページの部分は何も表示されていない
初期値なしの useState で map したページを開いたところ。ページは真っ白で、コンソールにエラーと警告が1件ずつ出た

なお、MDN の同じ解説によると、このまちがいでも Firefox では "x" is undefined、Safari では undefined is not an object (evaluating 'obj.x') のように、ブラウザーによって文が変わります。

データが届く前の最初の表示では、posts が undefined になっている

useState の公式リファレンスには、最初の表示で返る state は、渡した初期値(initialState)と同じになると書かれています。初期値を渡さなければ、最初の posts は undefined です。TypeScript の型定義(@types/react 19.3.0)でも、引数なしの useState<S>() が返す値の型は S | undefined になっていました。

一方、useEffect の公式リファレンスにあるとおり、useEffect に渡した処理が動くのは、コンポーネントがページに加わったときです。そのため、取得の結果を setPosts で入れるより前に、まず posts が undefined のまま return の JSX が実行され、posts.map でエラーになります。

検証では、このページを開いても /api/posts.json へのリクエストは1回も出ませんでした。最初の表示がエラーで止まり、コンポーネントがページに加わらないまま、useEffect の中の fetch まで進まなかったことになります。直したページでは、同じ条件でリクエストが出ていました。

初期値を空の配列にすると、エラーが消える

いちばん手早い直し方は、useState に空の配列を渡すことです。変えたのは1行だけです。

tsx
// 直したもの:初期値を空の配列にする
const [posts, setPosts] = useState<Post[]>([]);

このページを同じ開発サーバーで開くと、コンソールにはエラーも警告も出ませんでした。開いて 0.3 秒後の #root の中は空の <ul></ul> で、開いて 2 秒後(API の応答が届いたあと)には、猫の爪とぎの選び方 と キャットタワーの置き場所 の2件が <li> で並びました。

空の配列の map は何も返さないので、届く前は空のリストが表示されます。ただし、この書き方では「まだ届いていない」のか「0件だった」のかを、画面でもコードでも見分けられません。

届くまで「読み込み中…」を出すと、0件と区別できる

取得中であることを画面に出したいときは、初期値なしのまま、undefined の間だけ別の JSX を返します。条件によって別の JSX を返す書き方は、公式の学習ページにある条件付きレンダーの説明で紹介されています。

tsx
// 直したもの:届くまでは「読み込み中…」を出す
export default function PostList() {
  const [posts, setPosts] = useState<Post[]>();

  useEffect(() => {
    fetch('/api/posts.json')
      .then((res) => res.json())
      .then((data: Post[]) => setPosts(data));
  }, []);

  if (posts === undefined) {
    return <p>読み込み中…</p>;
  }

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

if のあとでは posts が配列だと TypeScript にも分かるので、posts.map の行で型のエラーにもなりません。開いて 0.3 秒後の #root の中は <p>読み込み中…</p> で、2 秒後には2件の <li> に変わりました。コンソールにはエラーも警告も出ませんでした。

直したページに「猫の爪とぎの選び方」「キャットタワーの置き場所」の2行が箇条書きで表示されている。下の DevTools のコンソールには、React DevTools の案内の1行だけが出ている
届くまで読み込み中を出すように直したページ。届いたあとに一覧が表示され、エラーは出ていない

コンソールに残っている1行は、React DevTools の案内です。エラーとは関係なく、直す前のページにも出ていました。

TypeScript なら tsc で見つかるが、開発サーバーは止まらない

初期値なしの useState<Post[]>() で posts.map と書くと、型チェックでエラーになります。検証用のプロジェクトで npx tsc -p tsconfig.app.json --noEmit を実行すると、次のエラーが出ました。

text
src/BadNoInitial.tsx(16,8): error TS18048: 'posts' is possibly 'undefined'.

テンプレートの npm run build は最初に tsc を実行するので、このまま本番用のビルドに進むこともありません。ただし、Vite のドキュメントにあるとおり、開発サーバーは型チェックをしないので、さきほどのように画面を開けてしまいます。tsc のエラーを見落とさなければ、ブラウザーで開く前に気づけます。

テンプレートに入っている lint ツールの oxlint を、設定を変えずに npx oxlint src で実行したところ、何も報告されませんでした。

初期値が空の配列でも、応答のキーを取り違えると出る

初期値を空の配列にしていても、同じ文のエラーになることがあります。次のコンポーネントでは、API が { "items": [...] } の形で返すのに、data.posts を setPosts に入れています。

tsx
// まちがい:API は { items: [...] } を返すのに、data.posts を入れている
const [posts, setPosts] = useState<Post[]>([]);

useEffect(() => {
  fetch('/api/posts-page.json')
    .then((res) => res.json())
    .then((data) => setPosts(data.posts));
}, []);

開いて 0.3 秒後の #root の中は空の <ul></ul> で、この時点ではエラーはありませんでした。API の応答が届いたあとに Cannot read properties of undefined (reading 'map') のエラーと An error occurred in the <PostList> component. の警告が出て、2 秒後には #root の中が空になりました。data にない posts を読むと undefined になり、それが posts に入ったためです。

res.json() の戻り値は any なので、このコードは tsc でエラーになりませんでした。応答の形を型で書き、data.items を入れるように直すと、エラーは消え、2件の <li> が表示されました。

tsx
// 直したもの:API が返すキー(items)から配列を取り出す
type PostsResponse = { items: Post[] };

// (useEffect の中)
.then((data: PostsResponse) => setPosts(data.items));

エラーが開いた直後に出るか、少したってから出るかで、原因の見当がつきます。開いた直後なら初期値、データが届いたあとなら応答の形を確かめます。

補足

本番用にビルドしたページ(npx vite build のあと npx vite preview で開いたもの)でも、エラーの文は Cannot read properties of undefined (reading 'map') のままでした。React の番号つきのエラー(Minified React error #...)にはならず、警告の An error occurred in ... は出ませんでした。画面が真っ白になるのは開発中と同じです。

​Posted by 86