Expressのエラー処理：エラーミドルウェアと非同期エラー

Expressは、4つの引数 (err, req, res, next) を取り、すべてのルートの後に登録される特別なミドルウェアでエラーを処理します。Expressは、ルートの中で投げられたエラー、next(err) に渡したエラー、そしてExpress 5では async ハンドラーからrejectされたPromiseのすべてをそこへ送ります。ハンドラーがステータスコードを決めてエラーのレスポンスを1つ送るので、ほかのコードはただ例外を投げればよくなります。

const express = require('express');
const app = express();

const users = [{ id: 1, name: 'Ada' }];

app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) {
        const err = new Error(`No user with id ${req.params.id}`);
        err.status = 404;
        throw err;
    }
    res.json(user);
});

// The error handler: four arguments, after the routes.
app.use((err, req, res, next) => {
    console.log('error handler:', err.message);
    res.status(err.status ?? 500).json({ error: err.message });
});

// GET /users/99
app.listen(3000);

GET /users/99 は 404 と {"error":"No user with id 99"} を返し、Consoleにはエラーハンドラーが出した行が表示されます。GET /users/1 を送るとルートは普通に答えます。エラーハンドラーが動くのは、何か問題が起きたときだけです。

Expressが捕まえてくれるエラー

ルートからエラーハンドラーに届く方法は3つあり、Express 5ではどれも同じように動きます。

// Each route throws on purpose to reach the error handler.
const express = require('express');
const app = express();

app.get('/sync', (req, res) => {
    throw new Error('Thrown in a route');
});

app.get('/next', (req, res, next) => {
    next(new Error('Passed to next()'));
});

app.get('/async', async (req, res) => {
    await new Promise((resolve) => setTimeout(resolve, 10));
    throw new Error('Rejected in an async route');
});

app.use((err, req, res, next) => {
    res.status(500).json({ error: err.message });
});

// GET /async
app.listen(3000);

GET /async は 500 と {"error":"Rejected in an async route"} を返します。GET /sync と GET /next も、それぞれのメッセージで同じハンドラーにたどり着きます。今度はエラーハンドラーの引数から next を消して、GET /sync をもう一度送ってみてください。引数が3つだとExpressはそれを普通のミドルウェアとして扱って飛ばし、デフォルトのHTMLのエラーページで答えます。

非同期のエラー：Express 5とExpress 4

/async のルートが動くのは、Express 5がrejectされたPromiseを捕まえるからです。Express 4は捕まえませんでした。エラーは未処理のrejectになり、リクエストは止まったままでした。

Express 4では、asyncハンドラーをそれぞれラップするか、express-async-errors パッケージをインストールします。

// Express 4 only
const asyncHandler = (fn) => (req, res, next) =>
    Promise.resolve(fn(req, res, next)).catch(next);

app.get('/users/:id', asyncHandler(async (req, res) => {
    const user = await db.findUser(req.params.id);
    res.json(user);
}));

最後の行はどちらのバージョンでも同じです。Expressは、自分が呼んでいないコールバックの中で投げられたエラーを見ることができません。コールバックのAPIはPromiseに変え（Node.jsのほとんどには fs/promises のようなPromise版があります）、それを await しましょう。

404ハンドラーと統一されたJSONのエラー

すべてのエラーが同じ形をしていると、APIは使いやすくなります。エラーに status を持たせ、マッチしないルートを404エラーに変え、1つのハンドラーですべてを整形しましょう。

const express = require('express');
const app = express();
app.use(express.json());

class HttpError extends Error {
    constructor(status, message) {
        super(message);
        this.status = status;
    }
}

const users = [{ id: 1, name: 'Ada' }];

app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) throw new HttpError(404, `No user with id ${req.params.id}`);
    res.json(user);
});

app.post('/users', (req, res) => {
    if (!req.body?.name) throw new HttpError(400, 'name is required');
    res.status(201).json({ id: 2, name: req.body.name });
});

// 404: no route matched.
app.use((req, res, next) => {
    next(new HttpError(404, `Cannot ${req.method} ${req.path}`));
});

app.use((err, req, res, next) => {
    if (res.headersSent) return next(err);
    const status = err.status ?? 500;
    if (status >= 500) console.log(err);
    res.status(status).json({
        error: status >= 500 ? 'Internal server error' : err.message,
        status,
    });
});

// GET /nope
app.listen(3000);

GET /nope はどのルートにもマッチしないので、404ハンドラーがそれをエラーに変え、返事は {"error":"Cannot GET /nope","status":404} になります。GET /users/99 を送ると、ルートが投げたエラーも同じ形になります。ボディ {"name": } で POST /users を送ると、express.json() がパースに失敗し、status が400のエラーで next() を呼ぶので、返事は {"error":"Unexpected token '}', \"{\"name\": }\" is not valid JSON","status":400} になります。

スタックトレースを漏らさない

自作の HttpError のメッセージはクライアント向けに書いたものです。それ以外（データベースのドライバーや、TypeError を投げるタイプミスなど）から来るメッセージやスタックは、ファイルパス、クエリ、ライブラリのバージョンを明かしてしまうことがあります。上のハンドラーは5xxにはすべて Internal server error を送り、本当のエラーは代わりにサーバーでログに残します。if (res.headersSent) return next(err); は、レスポンスの一部がすでに送られた後に起きたエラーへの対策です。その場合に安全なのは、Expressに接続を閉じさせることだけです。

Express自身のデフォルトのハンドラーは NODE_ENV に従い、NODE_ENV が production でない限り、HTMLのページにスタックトレースを含めます。本番サーバーでは設定しておきましょう（NODE_ENV=production node server.js）。ただし、それに頼るのはやめましょう。err.stack を決して送らない自作のハンドラーのほうが安全です。

よくある間違い

ルートより前にエラーハンドラーを登録する。 Expressはエラーを先へ渡すだけなので、ルートより上にあるハンドラーはそのルートのエラーを見ることがありません。404ハンドラーの後、最後に置きましょう。

エラーを捕まえて何もしない。 ログを取るだけの try/catch は、リクエストを止めたままにします。catch の中では next(err) を呼ぶか、投げ直すか、レスポンスを送りましょう。

レスポンスを2回送る。 res.json() の後で例外を投げると、エラーハンドラーがもう一度送ろうとします。例のように res.headersSent を確認しましょう。

普通のミドルウェアと next() の仕組みについては、Expressのミドルウェアを参照してください。