Node.jsのERR_HTTP_HEADERS_SENTの直し方

​​Node.js​Express,JavaScript,トラブルシュート

Node.js の ERR_HTTP_HEADERS_SENT は、1つのリクエストに対して、応答を返したあとでもう一度ヘッダーを書こうとしたときに出るエラーです。検証では、エラーの応答を返したあとの return の書き忘れと、時間切れの応答を返したあとに本来の結果も返す書き方の、2つの場合にこのエラーが出ました。応答を返したらその場で処理を終えるか、res.headersSent で返したかどうかを確かめると、エラーは消えます。

Node.js の http モジュールや Express で作った API サーバーに、入力のチェックやタイムアウトの処理を足して、応答を返す場所が2つになると、このエラーが出ます。私は検証環境で実際にこのエラーを起こし、出たメッセージをそのまま載せています。直したあとにエラーが消えることも確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、Express 5.3.0 で、リクエストは curl で送りました。出力の作業フォルダのパスは /path/to/app に置き換えています。応答ヘッダーは、毎回変わる Date や、この話に関係しない Content-Length などを省き、HTTP/1.1 … の行と Content-Type だけを載せています。Express 4 や、Fastify などほかのフレームワークでの動きは試していません。

エラーの意味

Node.js のエラーの一覧にある ERR_HTTP_HEADERS_SENT は、「ヘッダーを送ったあとに、さらにヘッダーを足そうとした」という意味です。ヘッダーを送ったあとに writeHead() や setHeader() を呼ぶと、このエラーになります。response.writeHead() の説明にも、1つの応答に1回だけ、response.end() より前に呼ぶと書かれています。

メッセージは、ヘッダーを送ったあとに、どのメソッドで書こうとしたかで変わります。検証では、writeHead() のときは Cannot write headers after they are sent to the client、setHeader() のとき(Express の res.send() や res.json() は中でこれを呼びます)は Cannot set headers after they are sent to the client と出ました。

原因1:エラーの応答を返したあとの return を忘れる

次の missing-return.mjs は、Node.js の http モジュールだけで作ったサーバーです。クエリパラメーターに name がなければ 400 を返しますが、そのあとの return を書き忘れています。

js
// 入力が足りないときに 400 を返すが、return を書き忘れている
import http from 'node:http';

const server = http.createServer((req, res) => {
  const url = new URL(req.url, 'http://localhost');
  const name = url.searchParams.get('name');
  if (!name) {
    res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
    res.end('name がありません\n');
  }
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end(`こんにちは、${name}さん\n`);
});

server.listen(3000, () => console.log('listening on 3000'));

name を付けたリクエスト、付けないリクエスト、もう一度付けたリクエストの順に送りました。

text
$ curl -s -i 'http://localhost:3000/?name=neko'
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

こんにちは、nekoさん

$ curl -s -i 'http://localhost:3000/'
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

name がありません

$ curl -s -i 'http://localhost:3000/?name=neko'

2回目のリクエストには、400 の応答が正しく返っています。ただ、サーバーはこの2回目を処理したところで、次のエラーを出して終了コード1で止まりました。そのため、3回目のリクエストは接続できず、何も返らないまま、curl は終了コード7(サーバーに接続できなかった)で終わりました。

text
listening on 3000
node:_http_server:354
    throw new ERR_HTTP_HEADERS_SENT('write');
    ^

Error [ERR_HTTP_HEADERS_SENT]: Cannot write headers after they are sent to the client
    at ServerResponse.writeHead (node:_http_server:354:11)
    at Server.<anonymous> (file:///path/to/app/missing-return.mjs:11:7)
    at Server.emit (node:events:519:28)
    at parserOnIncoming (node:_http_server:1186:12)
    at HTTPParser.parserOnHeadersComplete (node:_http_common:125:17) {
  code: 'ERR_HTTP_HEADERS_SENT'
}

Node.js v22.23.4

at で始まる行の2つ目 missing-return.mjs:11:7 が、2回目の writeHead() を書いた行です。if の中で 400 を返したあとも処理が続き、11行目で 200 のヘッダーを書こうとして失敗しています。まずはこの行を見て、その前にどこで応答を返しているかを探します。

直し方は、応答を返したところで return して、関数をそこで終えることです。

js

if (!name) {
    res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
    res.end('name がありません\n');
    return;
  }

同じ3つのリクエストを送ると、3回目にも 200 OK と こんにちは、nekoさん が返り、サーバーの出力は listening on 3000 だけで、エラーは出なくなりました。

Express ではサーバーは止まらず、ログにだけ出る

同じ書き間違いを Express 5 で書くと、こうなります。

js
// Express 5:入力が足りないときに 400 を返すが、return を書き忘れている
import express from 'express';

const app = express();

app.get('/hello', (req, res) => {
  if (!req.query.name) {
    res.status(400).send('name がありません');
  }
  res.send(`こんにちは、${req.query.name}さん`);
});

app.listen(3000, () => console.log('listening on 3000'));

/hello?name=neko、/hello、/hello?name=neko の順に送ると、curl には3回とも正しい応答(200、400、200)が返りました。サーバーも止まりません。ただ、サーバーのログには次のエラーが出ていました。

text
listening on 3000
Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client
    at ServerResponse.setHeader (node:_http_outgoing:700:11)
    at ServerResponse.header (/path/to/app/node_modules/express/lib/response.js:685:10)
    at ServerResponse.send (/path/to/app/node_modules/express/lib/response.js:141:14)
    at file:///path/to/app/express-missing-return.mjs:10:7
    at Layer.handleRequest (/path/to/app/node_modules/router/lib/layer.js:152:17)
    at next (/path/to/app/node_modules/router/lib/route.js:157:13)
    at Route.dispatch (/path/to/app/node_modules/router/lib/route.js:117:3)
    at handle (/path/to/app/node_modules/router/index.js:435:11)
    at Layer.handleRequest (/path/to/app/node_modules/router/lib/layer.js:152:17)
    at /path/to/app/node_modules/router/index.js:295:15 {
  code: 'ERR_HTTP_HEADERS_SENT'
}

http モジュールのときと違って止まらないのは、Express のエラー処理のガイドにあるとおり、ルートハンドラーの中で同期的に投げられた例外を、Express がキャッチするからです。そのぶん、ブラウザや curl からは何も問題がないように見えるので、ログを見ないと気づけません。

スタックトレースでは、node_modules の中の行を飛ばして、自分のファイルの行を探します。ここでは express-missing-return.mjs:10:7 で、2回目の res.send() を書いた行です。

Express でも、直し方は return を付けることです。return res.status(400).send(...) と1行で書けます。

js
app.get('/hello', (req, res) => {
  if (!req.query.name) {
    return res.status(400).send('name がありません');
  }
  res.send(`こんにちは、${req.query.name}さん`);
});

同じ3つのリクエストを送ると、応答は変わらず、ログにはエラーが出なくなりました。

原因2:時間切れの応答を返したあとに、本来の結果も返す

return を書いていても出るのが、時間切れの処理を自分で足した場合です。次の express-timeout.mjs は、1秒たったら 503 で「時間切れです」を返すようにしています。ところが、データの読み込み(ここでは1.5秒待つだけの関数で代わりにしています)が終わると、その結果も res.json() で返そうとします。

js
// Express 5:1秒で「時間切れ」を返すが、遅い処理のあとでも応答を返そうとする
import express from 'express';

const app = express();
const wait = (ms) => new Promise((r) => setTimeout(r, ms));

async function loadReport() {
  await wait(1500); // 遅いデータベースの代わり
  return { total: 42 };
}

app.get('/report', async (req, res) => {
  setTimeout(() => {
    res.status(503).json({ error: '時間切れです' });
  }, 1000);
  const report = await loadReport();
  res.json(report);
});

app.listen(3000, () => console.log('listening on 3000'));

curl には 503 の応答が返り、そのあと、サーバーのログに次のエラーが出ました。

text
$ curl -s -i 'http://localhost:3000/report'
HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8

{"error":"時間切れです"}
text
listening on 3000
Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client
    at ServerResponse.setHeader (node:_http_outgoing:700:11)
    at ServerResponse.header (/path/to/app/node_modules/express/lib/response.js:685:10)
    at ServerResponse.send (/path/to/app/node_modules/express/lib/response.js:141:14)
    at ServerResponse.json (/path/to/app/node_modules/express/lib/response.js:249:15)
    at file:///path/to/app/express-timeout.mjs:17:7 {
  code: 'ERR_HTTP_HEADERS_SENT'
}

17行目は、読み込みのあとの res.json(report) です。このときにはもう、タイマーの側で 503 の応答を返し終わっています。この関数は async なので、res.json() が投げた例外は Promise の失敗として Express に渡り、ログに出ました。Express 5 が、Promise を返すルートハンドラーの失敗を next() に渡すことも、上と同じガイドに書かれています。

このように、応答を返す場所が2つあり、どちらが先に動くかが時間で変わる書き方では、return では直せません。応答を返す前に、res.headersSent で、もう応答を返したかどうかを確かめます。headersSent は、ヘッダーを送ったあとなら true になる、読み取り専用の値です。

js
async function loadReport(ms) {
  await wait(ms); // 遅いデータベースの代わり
  return { total: 42 };
}

app.get('/report', async (req, res) => {
  const timer = setTimeout(() => {
    res.status(503).json({ error: '時間切れです' });
  }, 1000);
  const report = await loadReport(Number(req.query.ms ?? 1500));
  clearTimeout(timer);
  if (res.headersSent) {
    console.log('時間切れの応答を返したあとなので、結果は返さない');
    return;
  }
  res.json(report);
});

読み込みが先に終わったときは、clearTimeout() でタイマーを止めて、時間切れの応答が出ないようにしています。確かめるために、loadReport() には待つ時間を渡せるようにし、クエリパラメーターの ms で変えられるようにしました。

text
$ curl -s -i 'http://localhost:3000/report'
HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8

{"error":"時間切れです"}

$ curl -s -i 'http://localhost:3000/report?ms=200'
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"total":42}

1.5秒かかるときは 503 が返り、ログには 時間切れの応答を返したあとなので、結果は返さない と出て、エラーは出ませんでした。0.2秒で終わるときは、本来の結果の {"total":42} が返りました。

自分でエラー処理のミドルウェアを書くときも、同じ確かめ方を使います。Express のガイドでは、応答を書き始めたあとに next() にエラーが渡されると、Express の既定のエラー処理が接続を閉じると説明されています。ガイドには、自分で書くエラー処理のミドルウェアでは、res.headersSent が true なら自分で応答を返さず、return next(err) で既定のエラー処理に任せる例が載っています。

​Posted by 86