Reactの「A component suspended」エラーの直し方

​​React​lazy,startTransition,Suspense,TypeScript,トラブルシュート

React 18 で、ボタンを押してタブやモーダルの中身を lazy で読み込んだとき、画面が真っ白になって「A component suspended while responding to synchronous input」というエラーが出ることがあります。読み込み待ちになったコンポーネントの上に <Suspense> を置くか、ボタンで行う state の更新を startTransition で包むと直ります。

私は検証環境でこのエラーを起こし、出たメッセージと、2通りの直し方でエラーが消えることを確かめました。React 19 のブラウザー側では出ず、サーバーで HTML を作る renderToString で出ることも確かめています。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。npm create vite@latest の react-ts テンプレートで作ったプロジェクト(Vite 8.3.8、TypeScript 7.0.2)を2つ用意し、片方は react / react-dom 19.3.1、もう片方は 18.3.1(@types/react 18.3.31)にしました。ブラウザーは Playwright 1.63.0 で動かした Chromium 153 で、サーバーでの描画は tsx 4.23.15 で .tsx をそのまま実行しました。Next.js などのフレームワークや、use で Promise を読む書き方は試していません。

コンソールに出るエラーの全文

React 18.3.1 の開発サーバーで、下のコードのボタンを押すと、DevTools のコンソールに次の2つが出ました。

text
The above error occurred in one of your React components:

    at Lazy
    at div
    at App (http://localhost:5174/src/App.tsx:12:26)

Consider adding an error boundary to your tree to customize error handling behavior.
Visit https://reactjs.org/link/error-boundaries to learn more about error boundaries.
text
Uncaught Error: A component suspended while responding to synchronous input. This will cause the UI to be replaced with a loading indicator. To fix, updates that suspend should be wrapped with startTransition.
ボタンを押したあと、ページが真っ白になり、DevTools のコンソールに赤いエラーが2つ出ている画面
React 18.3.1 で、Suspense の外で読み込み待ちになったときのコンソール

メッセージの意味は「同期の入力に応えている最中に、コンポーネントが読み込み待ち(suspend)になった。これでは画面が読み込み中の表示に置き換わってしまう。直すには、待ちになる更新を startTransition で包むこと」です。1つめのエラーにある at Lazy が、待ちになったコンポーネントです。

本番用にビルドしたページでは、文が省略されて Minified React error #426 と出ました。React のエラーの説明ページ(426番)を開くと、上と同じ文が載っています。

エラーが出たコード

ボタンを押すと show が true になり、lazy で読み込む Detail を表示するコードです。読み込みに時間がかかる様子を見るため、検証では setTimeout で1秒遅らせました。Detail の上に <Suspense> はありません。

tsx
import { lazy, useState } from 'react';

// 読み込みに1秒かかるコンポーネント(検証用に遅らせている)
const Detail = lazy(
  () =>
    new Promise<typeof import('./Detail')>((resolve) => {
      setTimeout(() => resolve(import('./Detail')), 1000);
    }),
);

export default function App() {
  const [show, setShow] = useState(false);
  return (
    <div>
      <button onClick={() => setShow(true)}>詳細を表示</button>
      {show && <Detail />}
    </div>
  );
}

ボタンを押すと、ボタンも含めて画面の中身がすべて消えました。読み込みにかかる1秒を過ぎた1.6秒後も、画面は空のままでした。Component のリファレンスにある Error Boundary の説明のとおり、描画中のエラーを Error Boundary で受け止めていないと、React は画面から UI を取り除きます。

react-dom 18.3.1 のソースを見ると、待ちになったコンポーネントの上に Suspense がないとき、同期の更新(コメントでは sync/discrete update)でなければそのまま読み込みを待ち、同期の更新のときだけこのエラーを投げる作りになっていました。コメントには、同期の更新では、外部の状態とずれないように、画面の中身を一度にすべて作り切る必要があるため、という理由が書かれています。検証では、onClick の中でそのまま setShow を呼ぶとエラーになり、後で書く startTransition で包むとエラーになりませんでした。

直し方1:Suspense で囲んで、読み込み中の表示を出す

待ちになるコンポーネントの上に <Suspense> を置き、fallback に読み込み中の表示を渡します。変えたのは Detail の周りだけです。

tsx
import { lazy, Suspense, useState } from 'react';

// Detail の定義は上と同じ

export default function AppSuspense() {
  const [show, setShow] = useState(false);
  return (
    <div>
      <button onClick={() => setShow(true)}>詳細を表示</button>
      <Suspense fallback={<p id="loading">読み込み中…</p>}>
        {show && <Detail />}
      </Suspense>
    </div>
  );
}

React 18.3.1 でボタンを押すと、エラーは出ず、0.1秒後には「読み込み中…」、1.6秒後には「詳細を読み込みました」に変わりました。ボタンは消えずに残っています。

ボタンの下に「詳細を読み込みました」と表示され、DevTools のコンソールにエラーがない画面
Suspense で囲んだあとのコンソール。エラーは出ていない

lazy のリファレンスにある、Suspense と組み合わせる使い方と同じ形です。待ちになったときに読み込み中の表示に変わるのは、いちばん近い Suspense で囲んだ範囲です。Suspense のリファレンスにある例では、Suspense をページの根元近くに置いたため、ページのレイアウト全体が読み込み中の表示に置き換わっています。検証のように、Suspense を待ちになるコンポーネントの近くに置くと、ボタンなどほかの部分は残りました。

直し方2:startTransition で包んで、前の画面を残す

読み込み中の表示を出さず、読み込みが終わるまで今の画面を残したいときは、ボタンで行う state の更新を startTransition で包みます。

tsx
import { lazy, startTransition, useState } from 'react';

// Detail の定義は上と同じ

export default function AppTransition() {
  const [show, setShow] = useState(false);
  return (
    <div>
      <button
        onClick={() => {
          startTransition(() => {
            setShow(true);
          });
        }}
      >
        詳細を表示
      </button>
      {show && <Detail />}
    </div>
  );
}

React 18.3.1 でボタンを押すと、エラーは出ず、0.1秒後の画面はボタンだけのまま変わりませんでした。1.6秒後に「詳細を読み込みました」が出ました。

startTransition で包んだ更新は、急がない更新として扱われます。Suspense のリファレンスの、表示中の画面が fallback に置き換わるのを防ぐ方法にあるとおり、React は前の画面を残したまま、データがそろうのを待ちます。押したあと何も変わらないように見えるので、待っていることを見せたいときは useTransition の isPending を使います(useTransition のリファレンスにある、待っている状態を表示する方法)。

どちらを使うかは、読み込み中に何を見せたいかで決めます。新しく表示する部分に読み込み中の表示を出すなら Suspense、すでに表示している画面を残したいなら startTransition です。

React 19 のブラウザーでは、このエラーは出ない

同じ3つのコードを React 19.3.1 で動かしたところ、Suspense も startTransition もないコードでも、エラーは出ませんでした。ボタンを押して0.1秒後の画面はボタンだけのまま、1.6秒後に「詳細を読み込みました」が出て、startTransition で包んだときと同じ動きになりました。

react-dom 19.3.1 のファイルを synchronous input で検索すると、このメッセージがあったのは、サーバー用の react-dom-server-legacy で始まるファイルだけでした。18.3.1 では、ブラウザー用の react-dom.development.js にもありました。

ただ、エラーが出ないだけで、待っているあいだは押しても画面が変わりません。React 19 でも、読み込み中の表示を出すには Suspense で囲み、待っていることを見せるには isPending を使います。

サーバーの renderToString でも同じエラーが出る

React 19.3.1 と 18.3.1 のどちらでも、renderToString で HTML を作るとき、Suspense の外で待ちになるコンポーネントがあると、同じメッセージのエラーが投げられました。

tsx
import { renderToString } from 'react-dom/server';

// PageBroken は、<main> の中で lazy の Detail を Suspense なしで描くコンポーネント
console.log(renderToString(<PageBroken />));
text
Error: A component suspended while responding to synchronous input. This will cause the UI to be replaced with a loading indicator. To fix, updates that suspend should be wrapped with startTransition.

サーバーには押されたボタンがないので、メッセージの「startTransition で包む」は当てはまりません。直し方は2つあります。

1つは、Detail を <Suspense fallback={<p>読み込み中…</p>}> で囲むことです。エラーは消え、HTML には読み込み中の表示が入りました(React 19.3.1 での出力です。長い部分と属性の一部は「…」で省きました)。

html
<main><h1>商品ページ</h1><!--$!--><template data-msg="…The server used &quot;renderToString&quot; which does not support Suspense. …" …></template><p>読み込み中…</p><!--/$--></main>

renderToString のリファレンスにも、renderToString は待たずに、いちばん近い Suspense の fallback を HTML に入れると書かれています。中身はブラウザーでコードが読み込まれてから表示されます。

もう1つは、読み込みを待つ API に変えることです。静的な HTML を前もって作るなら、React 19 の react-dom/static にある prerender が使えます。Suspense のない同じコンポーネントを渡すと、エラーは出ず、1056ミリ秒後に中身まで入った HTML ができました。

tsx
import { prerender } from 'react-dom/static';

const { prelude } = await prerender(<PageBroken />);
console.log(await new Response(prelude).text());
html
<main><h1>商品ページ</h1><p id="detail">詳細を読み込みました</p></main>

prerender のリファレンスには、renderToString と違ってすべてのデータの読み込みを待つと書かれています。リクエストごとに HTML を返すサーバーなら、renderToString のリファレンスにある、ストリーミングの API へ移る方法も参考になります。

​Posted by 86