ビルド成功後もHTTP 500で応答するOpenNextのWorkerをCIで検出する

サマリ
- Next.js 16.4を@opennextjs/cloudflare 1.20.11までの1.20系でビルドすると、ビルドは成功するのに、Workerはリクエストにステータス500で応答する。
- ログには
Unexpected loadManifest(/.next/server/preview-props.json) call!が出力される。 - 同じアプリを
next startで起動するとステータス200で応答するので、Node.jsで実行する確認では検出できない。
- ログには
- 原因はNext.js 16.4がサーバーの初期化で必ず読み込むようになった
preview-props.jsonを、アダプタがWorkerにインライン化していなかったことにある。- 初期化で失敗するため、プリレンダリング済みのページも500になる。
- ファイル自体は成果物に存在し、インライン化の対象を選択するパターンに一致しなかった。
- アダプタを1.20.12以降に、Wranglerを4.148.0以降の4.xに更新すると500は解消する。
- 1.20.12がWranglerに4.148.0以降を要求するので、両方を1つの変更で更新する。
- Next.jsを16.3系に固定する回避は、セキュリティ更新を適用できないので採用しない。
- CIでビルドの成果物を本番と同じ種類のランタイム(workerd)で起動し、動的なルートの応答が200かを確認すると、この種類の500をデプロイ前に検出できる。
前提となるOpenNextの仕組み
マニフェストのビルド時のインライン化
Next.jsはルートの一覧やプリレンダリングの情報を、.nextの下のJSONファイル(マニフェスト)に保存する。
サーバーはこれをloadManifestという関数で読み込む。
Node.jsで実行するときは、この関数がファイルシステムから読み込む。
OpenNextの Cloudflare向けアダプタ(@opennextjs/cloudflare)でビルドするときは、アダプタがこの関数を置換する。
対象は.nextからファイル名のパターン(glob)で収集したマニフェストである。
置換後の関数には各マニフェストのJSONがコード中の値として記述され、実行時にはファイルを参照せずにその値が返却される。
インライン化されていないパスでは 例外を送出する。
Next.jsが欠落を許容する一部のマニフェストは例外の対象外で、空のオブジェクトが返却される。
workerdとwrangler dev
workerd はCloudflare Workersのランタイムのオープンソース版である。
wrangler dev は、Workerをworkerdで開発者のマシンやCIのランナー上で起動する。
opennextjs-cloudflare previewも 内部でwrangler devを使用する。
ビルドの成果物(.open-next/worker.js)をこれで起動すると、Node.jsではなく本番と同じランタイムでリクエストを処理できる。
ビルドが成功してもWorkerだけがステータス500で応答する
自社ではNext.jsを16.4.1に更新したとき、アダプタは1.20.2のままだった。
CIのnext buildとopennextjs-cloudflare buildは成功し、デプロイ後のWorkerは全リクエストにステータス500で応答した。
最小のアプリでのHTTP 500の再現
最小のApp Routerのアプリで、この組み合わせを再現した。
アプリはプリレンダリングするページ/と、リクエストごとに処理するRoute Handler /api/hello(force-dynamic)で構成した。
結果は次のとおり。
| アダプタ | next startの/api/hello |
Workerの/api/hello |
Workerの/ |
|---|---|---|---|
| 1.20.2 | 200 | 500 | 500 |
| 1.20.12 | — | 200 | 200 |
Wranglerは4.148.0に固定し、アダプタの版だけを1.20.2と1.20.12で変更した。
1.20.2ではWorkerのログに次のスタックトレースが出力される。
Error: Unexpected loadManifest(/.next/server/preview-props.json) call!
at loadManifest (.open-next/server-functions/default/handler.mjs)
at NextNodeServer.getPreviewProps (.open-next/server-functions/default/handler.mjs)
at new Server (.open-next/server-functions/default/handler.mjs)
at new NextNodeServer (.open-next/server-functions/default/handler.mjs)
new NextNodeServerの中で例外が発生しているので、ルートの処理の前の、サーバーの初期化で失敗している。
プリレンダリング済みの/も500になるのは、OpenNextではこのページもWorkerのサーバー処理を経由して返却されるからである。
この記事の障害かを判別する
Next.js 16.4とアダプタ1.20.11までの1.20系の組み合わせで上のメッセージが出力されていれば、この記事の障害に該当する。
メッセージのパスが別のファイルでも、同種の障害の可能性がある。
Next.js 16.2ではprefetch-hints.jsonのパスで同じ例外が報告された。
preview-props.jsonがインライン化の対象のglobに一致しない
draft mode(CMSの下書きを公開前に表示する機能)の鍵をpreview propsと呼ぶ。
Next.js 16.4はこれをprerender-manifest.jsonから.next/server/preview-props.jsonに分離した。
このファイルは サーバーの初期化時に必ず読み込まれる。
1.20.2のアダプタがインライン化の対象を選択するglobは次のとおりで、preview-props.jsonは名前の末尾が-manifestでないため一致しない。
1.20.0 から 1.20.11 までの各版のglobも同じである。
const manifests = await glob(
join(dotNextDir, "**/{*-manifest,required-server-files,prefetch-hints}.json"),
{ windowsPathsNoEscape: true }
);
ビルドの時点では一致しないファイルは単に対象外になるだけなので、ビルドは成功する。
アダプタを1.20.12以降に更新する
修正は 1.20.12 で導入された。
修正 はglobにserver/preview-props.jsonを追加するものである。
更新の前に、peerDependencies(同時に導入する必要のあるパッケージと、バージョンの範囲)を確認する。
npm view @opennextjs/cloudflare@1.20.12 peerDependencies
# { next: '>=15.5.28 <16 || >=16.4.1', wrangler: '^4.148.0', 'rclone.js': '^0.6.6' }
1.20.12は wrangler: '^4.148.0'を要求する。
1.20.2の要求は^4.86.0だったので、Wranglerも4.148.0以降の4.xに更新する。
peerDependenciesの不一致は、インストールやビルドの失敗として顕在化するとは限らない。
Next.jsのminorを更新するときは、アダプタとWranglerも1つの変更で更新し、peerDependenciesの範囲と整合させる。
HTTP 500の対処として採用しなかった案
- Next.jsを16.3系に固定する案は採用しなかった。
- アダプタの修正が公開されるまでの回避にはなる。
- 1.20.12は Next.js 16.4.1のセキュリティ更新にも追従している。
- 16.3系に固定している間は、この更新を適用できない。
preview-props.jsonに空のオブジェクトを返却するパッチも採用しなかった。- このファイルはdraft modeの鍵を格納している。
- 修正のPR も読み込まれなくてもよいマニフェスト向けの空のオブジェクトを返却する方法を採用せず、
preview-props.jsonの鍵をインライン化している。
CIでビルドの成果物をworkerdで起動する
Next.jsのminorの更新では、アダプタが対応するまでの間、この記事と同種の例外でWorkerがステータス500で応答する可能性がある。
そこで、CIでopennextjs-cloudflare buildの後に、成果物をwrangler devで起動して数本のURLにリクエストするスモークテストを追加した。
リクエストするURLとスクリプト
リクエストするURLにはデータベースや認証に依存せず常にステータス200で応答する動的なルートを選択する。
既存のルートに該当するものが無い場合、次のRoute Handlerが最小の例である。
// app/api/hello/route.ts
export const dynamic = "force-dynamic";
export function GET() {
return Response.json({ ok: true });
}
次のスクリプトはWorkerが起動するまで最大60秒待機する。
その後、動的なルートとプリレンダリング済みのページの応答が200かを確認する。
wrangler.jsoncのmainが.open-next/worker.jsを指していることを前提にしている。
wranglerと子プロセスのworkerdを1つのプロセスグループとして停止するため、setsidを利用する。
このため、setsidを利用できるLinuxのランナー(GitHub Actionsのubuntu-latestなど)で実行する。
#!/usr/bin/env bash
# usage: smoke.sh <port> opennextjs-cloudflare build の後に実行する
set -euo pipefail
port="$1"
log="$(mktemp)"
# wrangler と子プロセスの workerd をまとめて止めるため、別のプロセスグループで起動する
setsid npx wrangler dev --ip 127.0.0.1 --port "$port" >"$log" 2>&1 &
pid=$!
trap 'kill -- -"$pid" 2>/dev/null || true; wait "$pid" 2>/dev/null || true' EXIT
for _ in $(seq 60); do
grep -q "Ready on" "$log" && break
kill -0 "$pid" 2>/dev/null || { cat "$log"; exit 1; }
sleep 1
done
grep -q "Ready on" "$log" || { echo "not ready within 60s"; cat "$log"; exit 1; }
for path in /api/hello /; do
status="$(curl -sS --max-time 10 -o /dev/null -w '%{http_code}' "http://127.0.0.1:${port}${path}" || true)"
if [[ "$status" != 200 ]]; then
echo "FAIL ${path} (${status})"
tail -n 40 "$log"
exit 1
fi
echo "OK ${path}"
done
アダプタが1.20.2の成果物では、/api/helloで500を受信して終了コード1で終了し、ログにUnexpected loadManifestが出力される。
1.20.12と1.20.13の成果物では両方が200で、終了コードは0になる。
スモークテストのCIへの配置とデータベースなどへの接続先
GitHub Actionsでは、ビルドの後のステップに配置する。
- name: Build Cloudflare Worker
run: npx opennextjs-cloudflare build
- name: Smoke test Cloudflare Worker
run: ./scripts/smoke.sh 8787
静的なアセットはWorkerのサーバー処理を経由せずに配信される場合がある。
このため、スモークテストのリクエスト先には動的なルートを含める。
wrangler devは、WorkerからデータベースのD1やオブジェクトストレージのR2を利用するための設定(binding)をデフォルトでローカルのシミュレーターに接続する。
wrangler.jsoncでbindingにremote: trueを指定した設定では、接続先はデプロイ済みのリソースとなる。
CIではその指定を削除した一時的な設定ファイルを作成し、スクリプトのwrangler devの行に-c <設定ファイル>を追加する。
データベースを参照するAPIにもリクエストするなら、起動の前にローカルのD1へマイグレーションを適用する。
コマンドはwrangler d1 migrations apply <database> --local -c <設定ファイル>である。
このスモークテストで分かるのはビルドの成果物がCIのランナー上のworkerdで起動し、リクエストを処理できることまでである。
本番のsecretの設定、本番のD1やR2に保存されたデータ、Cloudflare Accessの設定に起因する失敗は検出できない。


