ハイドレーションエラーは、サーバーが返したHTMLと、ブラウザでReactが最初に描いた結果が一致しないときに出るエラーです。React 19では開発中に Hydration failed because the server rendered text didn't match the client. などの文が、本番では Minified React error #418 という番号だけが出ます。この記事では、React 19.3.1(2026年10月14日公開)と18.3.1で同じ不一致を実際に起こして出力を記録し、貼り付けたエラー文から原因と直し方を引けるように整理しました。
まとめ:ハイドレーションエラーの要点
- 意味:SSRやSSGで作ったHTMLと、クライアントの初回描画が食い違った状態です。テキストや要素の不一致では、Reactは該当するSuspense境界内またはReactルートをクライアント側で作り直します。属性だけの不一致では、この再生成は行われません。
- React 19の番号:テキストや要素の不一致は
#418(URLのargs[]=textがテキスト、args[]=HTMLが要素)。React 18で出ていた#425は、19.3.1では出ませんでした。#423はハイドレーション中に例外が起きて回復したときの番号です。 - 見落としやすい点:class・style・idなど属性だけの不一致は、本番ビルドでは何も出ず、DOMはサーバー側の値のまま残ります。
- 主な原因:Date・タイムゾーン、Math.randomのID、windowやlocalStorageの参照、
<p>の中の<div>のような不正なネスト、ブラウザ拡張によるDOMの書き換え。 - 直し方の順番:まず同じ値をサーバーとクライアントで出す(タイムゾーン固定・useId)→ 出せない値はマウント後に描く(useEffect・useSyncExternalStore)→ 部品ごとSSRから外す(next/dynamicのssr: false)。suppressHydrationWarningは1階層しか効かないため最後に使います。
ハイドレーションエラーの意味と発生する仕組み
ハイドレーションは、サーバーで作ったHTMLをそのまま使い、そこにReactがイベントハンドラーと状態を結び付けて操作できる画面にする処理です。React公式の hydrateRoot のリファレンス は、サーバーとクライアントで描く内容が同じであることを前提にしています。
Reactは既存のDOMを1つずつたどり、クライアントで描いた結果と照合します。どこかで食い違うと、その部分のサーバーHTMLを信用できなくなり、クライアントで作り直します。作り直しの間に画面がちらつき、入力中の値やスクロール位置が失われることもあります。SSR・SSG・CSRの違いは CSRとSSRの違いと使い分け|Next.js 16で初期HTMLと表示速度を実測比較 で、Next.jsでの方式の選び方は Next.jsのレンダリング方式|SSG・ISR・SSR・CSRの違いとApp Routerでの選び方 で扱っています。
エラーメッセージ別の意味と直し方(React 19.3.1で実測)
以下はReact 19.3.1の renderToString で作ったHTMLを、jsdom上で hydrateRoot したときに実際に出た文です。開発ビルド(NODE_ENV=development)と本番ビルド(NODE_ENV=production)の両方で記録しました。
| 起こした不一致 | 開発ビルドの出力 | 本番ビルドの出力 | DOM |
|---|---|---|---|
| テキスト(時刻など) | Hydration failed … rendered text | #418 args[]=text | 作り直し |
| 要素の種類(span→b) | Hydration failed … rendered HTML | #418 args[]=HTML | 作り直し |
| p の中に div | In HTML, <div> cannot be … + Hydration failed | #418 args[]=HTML | 作り直し |
| class・style の値 | A tree hydrated but some attributes … | 出力なし | サーバー値のまま |
| 拡張機能が付けた属性 | A tree hydrated but some attributes … | 出力なし | 属性が残る |
| 描画中の例外(初回だけ) | There was an error while hydrating … | #423 | root全体を作り直し |
検証にはNode 26.5.0、React/React DOM 19.3.1、jsdom 30.1.3を使用しました。React 18との比較ではReact/React DOMを18.3.1に揃えています。jsdomはHTMLの仕様どおりにパースするため、<p> の中の <div> はブラウザと同じく分割されます。
「Hydration failed because the server rendered text/HTML didn’t match the client」
React 19で最も多く見る文です。全文は Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. で、続けてReact自身が原因の候補を5つ挙げます。typeof window !== 'undefined' による分岐、Date.now() や Math.random()、利用者のロケールでの日付整形、HTMLと一緒に送っていない外部データ、不正なタグのネストです。最後に拡張機能がDOMを書き換えた可能性にも触れています。
文の末尾には差分が付きます。+ がクライアントの値、- がサーバーの値です。時刻を表示する <p> なら + client-time と - server-time のように並ぶので、どの値が食い違ったかはここで分かります。text と出ればテキストの不一致、HTML と出れば要素の種類や構造の不一致です。React 18では同じ状況で Hydration failed because the initial UI does not match what was rendered on the server. と出ていました。
「A tree hydrated but some attributes of the server rendered HTML didn’t match the client properties. This won’t be patched up.」
属性だけが食い違ったときの文で、テキストや要素の不一致とは扱いが違います。Reactはツリーを作り直さず、属性も直しません(This won't be patched up.)。サーバーで class="a"、クライアントで className="b" を描いた実験では、ハイドレーション後もDOMは class="a" のままでした。
しかも本番ビルドでは、この不一致について何も出力されませんでした。開発では警告が出るのに本番のログには残らず、見た目だけが違う不具合になります。styleの値、Math.random() で作ったidでも同じ結果でした。この文が出たら、警告を消すより先に属性の値をサーバーとクライアントで揃えてください。拡張機能が付けた属性でもこの文が出ます(後述)。
「In HTML, <div> cannot be a descendant of <p>. This will cause a hydration error.」
Reactが描くタグの組み合わせがHTMLの仕様に反しているときに出る文で、<a> の中の <a>、<p> の中の <p>、<button> の中の <button> でも同じ形で出ます。ブラウザは <p><div>…</div></p> というHTMLを受け取ると、<p> をその場で閉じて <div> を外に出します。ReactはDOMの中に自分が描いたはずの構造を見つけられず、続けて Hydration failed … rendered HTML を出します。
In HTML, <html> cannot be a child of <body>. や <div> cannot be a child of <html> も同じ仲間で、レイアウトで <html> や <body> を二重に描いているか、<html> の直下に <div> を置いているときに出ます。Next.jsのApp Routerでは、<html> と <body> を書くのはルートレイアウトだけにします。<tr> cannot be a child of <table> は <tbody> を省いた表で出ます。
「There was an error while hydrating」(#423・#422)
React 19では、#423と#422は不一致の番号ではありません。ハイドレーション中にコンポーネントが例外を投げ、クライアントでの描き直しで回復できたときの番号です。初回の描画だけ例外を投げる部品で試すと、Suspense の外では There was an error while hydrating but React was able to recover by instead client rendering the entire root.(本番は#423)、Suspense の内側では … from the nearest Suspense boundary.(本番は#422)が出ました。error.cause には元の例外が入っています。
React 19で#423だけが出るなら、不一致ではなく、ハイドレーション中に動かした処理(localStorageの読み取りなど)の例外を疑ってください。
本番の「Minified React error #418」を読む手順と番号の変化
本番ビルドのReactは文を省き、Minified React error #418; visit https://react.dev/errors/418?args[]=text&args[]= for the full message のように番号とURLだけを出します。URLを開くと、facebook/react の codes.json に登録された文の %s に args[] の値を入れた全文が出ます。ただし本番のエラー本文には差分が付きません。部品の手がかりは onRecoverableError の第2引数 componentStack に入り、19.3.1の本番ビルドでも部品名(実験では at NamedWidget)が出ましたが、アプリのビルドで関数名が圧縮されていれば読めません。確実なのは開発ビルドで同じ画面を開き直すことです。
番号の意味はReactの版で変わりました。同じ不一致をReact 18.3.1と19.3.1で起こした結果です。
| 本番ビルドで起きたこと | React 18.3.1 | React 19.3.1 |
|---|---|---|
| テキストの不一致 | #425 と #423 | #418(args[]=text) |
| 要素の不一致 | #418 と #423 | #418(args[]=HTML) |
| 描画中の例外から回復 | #423 | #423(Suspense内は#422) |
| 案内先URL | reactjs.org/docs/error-decoder | react.dev/errors/番号 |
codes.jsonには今も#425(Text content does not match server-rendered HTML.)が残っていますが、19.3.1の本番用ファイル(react-dom-client.production.js)には#425を出す箇所がありませんでした。「Text content does not match」や「initial UI does not match」で見つかる解説はReact 18時代のもので、原因と直し方は同じですが、エラー文と番号は読み替えが必要です。React 19で何が変わったかは Reactの最新バージョンは19.3|React 19の新機能・18との違いと確認・更新方法 にまとめています。
作り直される範囲とSuspense境界
不一致が起きたとき、Reactがどこまで作り直すかは Suspense の置き方で変わります。見出しの <h1> と時刻の <p> を並べ、<p> の中身だけをサーバーとクライアントで変えて比べました。
- Suspenseなし:食い違ったのは
<p>だけでも、<h1>のDOMノードまで別のものに置き換わりました。 - <p> だけを Suspense で包む:
<h1>のDOMノードはそのまま残り、作り直されたのは<p>だけでした。
原因をすぐに直せない部品があるなら、その部品を Suspense で包んでおくと、ちらつきや入力値の消失をその範囲に閉じ込められます。根本の対処ではなく、本番の被害を小さくする手段です。
原因別のハイドレーションエラーの直し方
Next.js公式のエラー解説 は、不正なネスト・windowの参照・時刻・ブラウザ拡張・CSS-in-JS・CDNなど7つの原因を挙げています。直し方は副作用が小さい順に「同じ値を出す」「マウント後に描く」「SSRから外す」です。
Dateの日付表示とロケール・タイムゾーンの固定
サーバーがUTCで動き、利用者のブラウザが日本時間だと、同じ時刻でも文字列が変わります。2026-10-28T00:00:00Zを描くと、サーバーは 00:00、ブラウザは 09:00 となり、#418(args[]=text)が出ました。
// NG: サーバー(UTC)とブラウザ(日本時間)で表示が変わる
export function Clock({ iso }) {
return <p>{new Date(iso).toLocaleTimeString('ja-JP', { hour: '2-digit', minute: '2-digit' })}</p>;
}
表示するタイムゾーンを Intl.DateTimeFormat の timeZone で決めておけば、どちらで描いても 09:00 になり、エラーは出ませんでした。
// OK: タイムゾーンを固定すれば、どこで描画しても同じ文字列になる
const fmt = new Intl.DateTimeFormat('ja-JP', {
timeZone: 'Asia/Tokyo',
hour: '2-digit',
minute: '2-digit',
});
export function Clock({ iso }) {
return <time dateTime={iso}>{fmt.format(new Date(iso))}</time>;
}
「3分前」のような相対時刻や、利用者ごとのタイムゾーンで出したい場合は、サーバーでは日付だけを出し、細かい表示はマウント後に描く(次の項)方法にします。
Math.randomによるID生成とuseIdへの置き換え
フォームの id と htmlFor を Math.random() で作ると、属性の不一致になります。前章のとおり、本番では何も出ずにDOMがサーバーの値のまま残るので、気付きにくい原因です。Reactの useId は、サーバーとクライアントでコンポーネントツリーが一致し、指定するidentifierPrefixも同じなら、対応する呼び出しで同じ値を返します(実測では _R_0_)。
import { useId } from 'react';
export function EmailField() {
// NG: const id = 'email-' + Math.random().toString(36).slice(2);
const id = useId(); // サーバーとクライアントで同じ値になる
return (
<>
<label htmlFor={id}>メールアドレス</label>
<input id={id} type="email" />
</>
);
}
window・localStorageのマウント後の読み取り
サーバーからは、利用者のブラウザのwindowやlocalStorageは読めません(Node.js 26.5.0の localStorage は --localstorage-file を指定しないと未定義で、指定してもサーバー側のファイルです)。typeof window !== 'undefined' で分岐すると、サーバーとクライアントで別の結果を描くことになり、これ自体が不一致の原因です。React公式が勧めるのは、初回はサーバーと同じ内容を描き、useEffect の中で値を読んでから描き直す「二度描き」です。
'use client';
import { useEffect, useState } from 'react';
export function SavedTheme() {
const [theme, setTheme] = useState(null); // 初回はサーバーと同じ null
useEffect(() => {
setTheme(localStorage.getItem('theme') ?? 'light');
}, []);
if (theme === null) return <span>テーマを読み込み中</span>;
return <span>現在のテーマ:{theme}</span>;
}
同じことは useSyncExternalStore の3つ目の引数 getServerSnapshot でも書けます。この関数はサーバー描画とハイドレーションの間だけ使われるので、そこで false を返すと、ハイドレーション後に true へ切り替わります。開発・本番とも警告は出ませんでした。
'use client';
import { useSyncExternalStore } from 'react';
const subscribe = () => () => {};
// サーバー描画とハイドレーション中は false、その後は true を返す
export function useIsClient() {
return useSyncExternalStore(subscribe, () => true, () => false);
}
どちらも初回はプレースホルダーが一瞬見えます。レイアウトがずれないよう、プレースホルダーは本来の表示と同じ高さにしておきます。useEffectとuseSyncExternalStoreの位置付けは Reactフック(Hooks)とは?全18種の一覧とReact Compiler時代の使い分け【2026年8月版】 で扱っています。
ブラウザ専用部品のnext/dynamicによるSSR除外
地図ライブラリやグラフ描画のように、読み込んだ瞬間にwindowを触る部品は、部品ごとサーバー描画から外します。Next.jsの next/dynamic に ssr: false を付けると、その部品はクライアントだけで描かれ、不一致の対象になりません。
App Routerでは、ssr: false を Server Component の中で使うとエラーになります(Next.js公式のLazy Loading)。'use client' を付けた読み込み用の部品を1枚挟み、その中で dynamic を呼びます。
// app/map/map-loader.jsx(Client Component にする)
'use client';
import dynamic from 'next/dynamic';
const Map = dynamic(() => import('./map'), {
ssr: false,
loading: () => <p>地図を読み込み中</p>,
});
export default function MapLoader() {
return <Map />;
}
SSRから外した部品は、検索エンジンが受け取るHTMLにも中身が入りません。本文や見出しのように検索に載せたい部分には使わず、地図・グラフ・エディターなどの操作部品に限ります。Next.jsの最新の版と変更点は Next.js 16の最新バージョンは16.4|リリース履歴・LTS期限・セキュリティ修正版と更新手順 で追っています。
不正なHTMLネストの修正とリンクの分離
不正なネストは、suppressHydrationWarningでも ssr: false でも正しくは直りません。ブラウザがHTMLを組み替えてしまうため、タグを直すしかありません。Next.jsの Link は <a> を出すので、カード全体を Link で包んだ中に別の Link を置くと <a> の入れ子になります。
// NG: <p> の中に <div>、<a> の中に <a>
<p>価格:<div className="price">1,980円</div></p>
<Link href="/item/1">
<article>
<Link href="/shop/1">ショップへ</Link>
</article>
</Link>
// OK: ブロック要素は <div> で包む/リンクは入れ子にしない
<div>価格:<span className="price">1,980円</span></div>
<article>
<Link href="/item/1">商品を見る</Link>
<Link href="/shop/1">ショップへ</Link>
</article>
CMSから受け取ったHTMLを dangerouslySetInnerHTML で <p> の中に入れる場合も、CMS側に <div> や <p> が含まれていると同じことが起きます。受け皿は <div> にしてください。
ブラウザ拡張の属性追加とiOSの自動リンクへの対処
ブラウザ拡張の中には <body> に属性や要素を足すものがあり、ColorZillaが cz-shortcut-listen="true" を付けてNext.js 15とReact 19で不一致が出た報告があります(vercel/next.js #72031)。React 19は、<head> と <body> に外から差し込まれた要素を読み飛ばすようになりました(React 19の公開告知)。文書全体をハイドレーションする実験でも、<head> に足した <script> と <body> の末尾に足した <div> ではエラーが出ず、要素も消されませんでした。
一方で、<body> に cz-shortcut-listen 属性を手で付けて試すと、19.3.1でも開発ビルドで A tree hydrated but some attributes … が出ました。<body> に suppressHydrationWarning を付けると消えます。対象は <body> 自身の属性だけで、子孫の不一致は今までどおり検出されます。
iOSのSafariは、本文中の電話番号やメールアドレスを自動でリンクに変えます。Next.js公式は、これで不一致が起きる場合の対処として format-detection のmetaタグを示しています。
// app/layout.jsx
export default function RootLayout({ children }) {
return (
<html lang="ja">
<head>
<meta name="format-detection" content="telephone=no, date=no, email=no, address=no" />
</head>
<body suppressHydrationWarning>{children}</body>
</html>
);
}
拡張機能が原因かどうかは、通常のウィンドウで拡張機能だけを無効にして同じページを開くと切り分けられます。シークレットウィンドウでも拡張機能は既定で止まりますが、Cookieや保存データも変わるため、保存データに依存する自分のコードの不具合と区別できません。
CDNによるHTML変更とCSS-in-JSのSSR設定
CDNやプロキシがHTMLを圧縮・書き換えすると、Reactが受け取るHTMLが描いたものと変わります。Next.js公式はCloudflareのAuto Minifyを例に挙げていますが、Auto Minifyは2024年に廃止されたので、今はほかの最適化機能やWAFのHTML書き換えを疑います。curl で取ったHTMLと、サーバーのログに残る出力を比べれば、途中で変わったかどうかが分かります。styled-componentsやEmotionなどのCSS-in-JSは、App Routerへの対応状況とSSRの設定がライブラリごとに違うため、Next.js公式のCSS-in-JSガイド で使っているライブラリの手順を確認します。設定が足りないと、スタイルの欠落や属性の不一致につながります。
suppressHydrationWarningを使ってよい場面と1階層の制限
suppressHydrationWarning は、その要素の属性と直下のテキストの不一致について警告を出さないようにする属性です。React公式 は、効くのは1階層だけで、逃げ道として使い、多用しないよう書いています。
// 効く:この要素の直下のテキストと属性だけが対象
<time dateTime={iso} suppressHydrationWarning>{formatted}</time>
// 効かない:子要素 <span> の中の不一致は対象外
<div suppressHydrationWarning>
<span>{formatted}</span>
</div>
実際に試すと、<time> に付けた場合は開発・本番とも何も出ず、DOMはサーバーの値(10:00)のまま残りました。Reactは食い違ったテキストを直しません。一方、<div> に付けて子の <span> の中身を変えると、通常どおり Hydration failed(本番は#418)が出ました。
使ってよいのは、ずれても困らず、ずれを直す必要もない値に限られます。投稿日時の <time>、拡張機能の属性を受け止める <html> と <body>、テーマ切り替えのライブラリが <html> の class を書き換える場合です。価格・在庫・ログイン状態のように、サーバーの値が残ると誤りになる表示には付けてはいけません。警告が消えるだけで、利用者には古い値が見え続けます。
ハイドレーションエラーを本番で見つける監視と予防
属性の不一致は本番ビルドで何も出さないため、開発中に潰すしかありません。テキストと要素の不一致は本番でも hydrateRoot の onRecoverableError に届くので、監視サービスへ送っておくと、特定のブラウザや拡張機能でだけ起きる不一致も拾えます。Next.jsのように hydrateRoot を自分で呼ばないフレームワークで監視サービスのSDKを使う場合は、本番ビルドでわざと不一致を起こし、ハイドレーションのエラーが実際に届くかを確かめてください。
import { hydrateRoot } from 'react-dom/client';
hydrateRoot(document.getElementById('root'), <App />, {
onRecoverableError(error, errorInfo) {
// 本番では "Minified React error #418; ...args[]=text" の形で届く
sendToMonitoring({
message: error.message,
cause: error.cause?.message,
componentStack: errorInfo.componentStack,
});
},
});
リリース前には次の5点を確認します。
- 描画中に
new Date()・Math.random()・toLocaleString()を使う場合、時刻・乱数の初期値をサーバーとクライアントで共有し、日付表示のロケールとタイムゾーンを揃えている - 描画中にwindow・localStorage・navigatorを読んでいない(useEffectかuseSyncExternalStoreの中だけ)
<p>の中のブロック要素、<a>や<button>の入れ子がない(開発ビルドのIn HTML, …がゼロ)- 本番用の値をサーバーで取得したら、同じ値をHTMLと一緒にクライアントへ渡している
- suppressHydrationWarningの付いた要素が、ずれても困らない値だけを表示している
SSRを含むWebアプリを設計から作り直すなら、どの値をサーバーで決めてクライアントへ渡すかを最初に決めておくと、この種の不一致は起きにくくなります。要件定義から実装まで任せたいときは フルスクラッチ開発 でもご相談を受けています。
よくある質問
ハイドレーションエラーは放置しても動きますか?
テキストや要素の不一致なら、Reactがクライアントで作り直すので画面は最終的に正しくなります。ただし作り直しの分だけ表示が遅れ、不一致を囲むSuspense境界がなければ、そのReactルートがクライアント描画へ切り替わり、入力値が失われることがあります。属性の不一致は作り直されず、サーバー側の値が残ったままになるので、放置すると表示の誤りとして残ります。
開発環境では出るのに、本番では何もエラーが出ないのはなぜですか?
属性だけの不一致(A tree hydrated but some attributes …)は、React 19.3.1の本番ビルドでは何も出力しません。エラーが出ないのは直ったからではなく、本番が報告しないだけです。開発ビルドで出た警告はそのまま本番の不具合として残っています。
ハイドレーション(hydration)の読み方と言葉の意味は?
「ハイドレーション」と読みます。英語のhydrationは「水分を与えること」で、サーバーから届いた乾いたHTMLに、ReactがJavaScriptの状態とイベントを注ぎ込んで動く画面にする様子をたとえた呼び名です。登山用の給水袋(ハイドレーションパック)とは関係ありません。
cz-shortcut-listen とは何ですか?
色を拾うブラウザ拡張ColorZillaが <body> に付ける属性で、Next.jsのissue(#72031)でハイドレーションの不一致の原因として報告されています。この属性が付くと A tree hydrated but some attributes … が出ます。コードの不具合ではないので、拡張機能を切って再現しないことを確かめ、<body> に suppressHydrationWarning を付けて受け止めます。
AstroやNuxt(Vue)でもハイドレーションエラーは起きますか?
起きます。サーバーのHTMLとクライアントの描画を照合する仕組みが同じだからです。Astroでは、ずれが避けられない部品を client:only="react" にするとサーバーで描かずクライアントだけで描きます(考え方は アイランドアーキテクチャとは?仕組みとAstro 7の実装・JS量の実測、PPRとの違い)。Vueは3.5以降、要素に data-allow-mismatch を付けると不一致の警告を抑えられます(Vue公式)。