Gestion des erreurs Express : middleware d'erreur et async

Express gère les erreurs avec un middleware spécial qui prend quatre arguments, (err, req, res, next), et qui est enregistré après toutes vos routes. Express lui envoie chaque erreur levée dans une route, chaque erreur passée à next(err) et, dans Express 5, chaque promesse rejetée d'un handler async. Le gestionnaire choisit le code de statut et envoie une seule réponse d'erreur, donc le reste de votre code peut se contenter de lever des erreurs.

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 répond 404 avec {"error":"No user with id 99"}, et la Console affiche la ligne du gestionnaire d'erreurs. Envoyez GET /users/1 et la route répond normalement ; le gestionnaire d'erreurs ne s'exécute que quand quelque chose se passe mal.

Les erreurs qu'Express intercepte pour vous

Une route a trois façons d'atteindre le gestionnaire d'erreurs, et dans Express 5 les trois fonctionnent de la même manière :

// 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 répond 500 avec {"error":"Rejected in an async route"} ; GET /sync et GET /next finissent dans le même gestionnaire avec leur propre message. Retirez maintenant next des paramètres du gestionnaire d'erreurs et renvoyez GET /sync : avec trois paramètres, Express le traite comme un middleware ordinaire, le saute et répond avec sa page d'erreur HTML par défaut.

Erreurs async : Express 5 et Express 4

La route /async fonctionne parce qu'Express 5 intercepte la promesse rejetée. Express 4 ne le faisait pas : l'erreur devenait un rejet non géré et la requête restait bloquée.

Avec Express 4, enveloppez chaque handler async ou installez le package 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);
}));

La dernière ligne est la même dans les deux versions : Express ne peut pas voir une erreur levée dans un callback qu'il n'a pas appelé. Transformez les API à callbacks en promesses (la plupart des modules de Node ont une version à promesses, comme fs/promises) et utilisez await.

Un handler 404 et des erreurs JSON cohérentes

Une API est plus simple à utiliser quand toutes les erreurs ont la même forme. Donnez un status aux erreurs, transformez les routes non trouvées en erreur 404, et laissez un seul gestionnaire les mettre en forme :

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 ne correspond à aucune route, donc le handler 404 la transforme en erreur et la réponse est {"error":"Cannot GET /nope","status":404}. Envoyez GET /users/99 et l'erreur levée par la route prend la même forme. Envoyez POST /users avec le corps {"name": } : express.json() n'arrive pas à le parser et appelle next() avec une erreur dont le status vaut 400, donc la réponse est {"error":"Unexpected token '}', \"{\"name\": }\" is not valid JSON","status":400}.

Ne divulguez pas les stack traces

Les messages de votre propre HttpError sont écrits pour le client. Les messages et les stacks de tout le reste (un driver de base de données, une faute de frappe qui lève une TypeError) peuvent révéler des chemins de fichiers, des requêtes et des versions de bibliothèques. Le gestionnaire ci-dessus envoie Internal server error pour chaque 5xx et journalise la vraie erreur côté serveur. if (res.headersSent) return next(err); couvre une erreur qui survient après qu'une partie de la réponse a déjà été envoyée : la seule chose sûre à faire est alors de laisser Express fermer la connexion.

Le gestionnaire par défaut d'Express suit NODE_ENV : il inclut la stack trace dans sa page HTML sauf si NODE_ENV vaut production. Définissez-la sur votre serveur de production (NODE_ENV=production node server.js), mais ne comptez pas dessus : un gestionnaire personnalisé qui n'envoie jamais err.stack est plus sûr.

Erreurs fréquentes

Enregistrer le gestionnaire d'erreurs avant les routes. Express ne fait passer les erreurs que vers l'avant, donc un gestionnaire placé au-dessus d'une route ne voit jamais les erreurs de cette route. Mettez-le en dernier, après le handler 404.

Intercepter une erreur sans rien en faire. Un try/catch qui ne fait que journaliser laisse la requête en suspens. Dans le catch, appelez next(err), relancez l'erreur ou envoyez une réponse.

Envoyer deux réponses. Lever une erreur après res.json() pousse le gestionnaire d'erreurs à essayer d'envoyer à nouveau. Vérifiez res.headersSent, comme dans l'exemple.

Pour le fonctionnement des middlewares ordinaires et de next(), voir les middlewares Express.