本文へスキップ
1 views

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

opennext-worker-smoke-workerd

サマリ

  • 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 }
);

ビルドの時点では一致しないファイルは単に対象外になるだけなので、ビルドは成功する。

sequenceDiagram participant B as opennextjs-cloudflare build participant W as Worker(workerd) participant N as NextNodeServerの初期化 B->>B: .nextからマニフェストをglobで収集し、loadManifestにインライン化する alt アダプタ1.20.11まで Note over B: preview-props.jsonはglobに一致せず、インライン化されない W->>N: 最初のリクエストでサーバーを生成する N->>N: loadManifest(server/preview-props.json) N-->>W: Unexpected loadManifestの例外 W-->>W: 500(プリレンダリング済みのページも) else アダプタ1.20.12以降 Note over B: preview-props.jsonもインライン化する W->>N: 最初のリクエストでサーバーを生成する N->>N: インライン化したpreview-props.jsonの中身を返却する N-->>W: ルートの処理を開始する end

アダプタを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系に固定する案は採用しなかった。
  • 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の設定に起因する失敗は検出できない。

この記事に出てくる用語

用語集の一覧へ

関連事例

  • セキュリティ診断・対策

    事例:新サービス公開前のセキュリティ診断と修正

    不動産の分野で事業を拡大する会社は、新サービスを公開する前に、悪用されうる脆弱性を解消できました。診断の結果を根拠に取引先へ安全を説明できる状態で、新サービスを公開しています。診断は開発支援会社の KDOT が担当し、修正はサイトによって KDOT と各サイトの開発会社が分担しました。

  • データ分析支援

    事例:過去実績を提案に活用する分析の仕組み

    広告代理店との取り組みです。同社は過去実績の示唆を次の提案へ反映し、結果をどのように予測したか、その背景まで提案先のクライアントへ説明できるようになりました。KDOT は案ごとの見込みと判断材料を比較できる仕組みを業務アプリとして実装しました。さらに業務アプリの中核となる処理ロジックと機械学習モデルについて、特許手続きを担う弁理士が技術の新規性や工夫を検討するための資料を作成しました。その後この発明には特許が付与されました。

お問い合わせ・ご相談

システム開発、データ活用、プロダクトづくりのことならお気軽にご相談ください。要件が固まる前の整理や、お見積もりだけのご依頼も承ります。