Next.js を AWS Lambda で動かすと 502 エラーが出る謎を解く。ストリーミングレスポンス設定の落とし穴

Next.js (App Router) を AWS Lambda (関数URL) でデプロイし、最新のストリーミング SSR を活用しようとしたところ、謎の 502 エラーに遭遇してハマったので備忘録として残します。

この記事でわかること
[現象] 突然の 502 Bad Gateway
[環境] 技術スタック
[原因] BUFFERED モードと Transfer-Encoding の不一致
[解決策] レスポンスストリーミングの有効化
- 1. AWS 設定の変更 (InvokeMode)
- 2. ハンドラーコードの修正
[まとめ]

この記事でわかること

Next.js と AWS Lambda のストリーミング不一致による 502 エラーの原因
Lambda 関数URLにおける「InvokeMode」の重要性
streamifyResponse を使用した具体的なコード修正方法

[現象] 突然の 502 Bad Gateway

Next.js を AWS Lambda 上で動かし、ブラウザからアクセスすると以下のエラーが表示されます。

ブラウザ上: 502 Bad Gateway (Lambda Proxy Error)
CloudWatch Logs: Runtime.InvalidResponse: The response from the function is invalid

ローカル環境や Vercel では正常に動作するコードが、Lambda 上でのみプロトコルエラーを起こしている状態です。

[環境] 技術スタック

Framework: Next.js 14 / 15 (App Router 使用)
Infrastructure: AWS Lambda + 関数URL (Lambda Function URL)
Deployment: AWS CDK または手動デプロイ

[原因] BUFFERED モードと Transfer-Encoding の不一致

Next.js 14/15 の App Router は、パフォーマンス向上のためデフォルトで出力をストリーミング (Streaming SSR) しようとします。これにより Transfer-Encoding: chunked ヘッダーが送信されます。

しかし、AWS Lambda 関数URLのデフォルト設定は BUFFERED モード です。このモードでは Lambda がレスポンス全体をメモリにバッファリングしてからクライアントへ返そうとしますが、ストリーミングデータ（チャンク化されたデータ）を正しくハンドリングできず、プロトコル違反として 502 エラーを吐き出します。

設定項目	BUFFERED (デフォルト)	RESPONSE_STREAM
挙動	レスポンスをすべて溜めてから送信	順次データを書き込みながら送信
ストリーミング SSR	不可 (502エラー)	可能
最大ペイロード	6MB	20MB (書き込み制限)

[解決策] レスポンスストリーミングの有効化

解決には「AWS インフラ設定」と「ハンドラーコード」の両方を修正する必要があります。

1. AWS 設定の変更 (InvokeMode)

Lambda 関数URLの設定で InvokeMode を RESPONSE_STREAM に変更します。CDK の場合は以下のように記述します。

const fnUrl = fn.addFunctionUrl({
  authType: lambda.FunctionUrlAuthType.NONE,
  invokeMode: lambda.InvokeMode.RESPONSE_STREAM, // ここを修正
});

2. ハンドラーコードの修正

標準的な Lambda ハンドラーではなく、aws-lambda ライブラリの streamifyResponse を使用してレスポンスをラップします。

[Before]

export const handler = serverless(app);

[After]

import { streamifyResponse } from 'aws-lambda';

export const handler = streamifyResponse(async (event, responseStream, _context) => {
  // nextServer.render 等で HTML ストリームを取得
  const result = await nextServer.render(event);

  responseStream.setContentType('text/html');
  responseStream.write(result);
  responseStream.end();
});