Une requête HTTP qui reste en attente indéfiniment, sans réponse, sans erreur dans les logs, sans crash du process : c'est le symptôme le plus déroutant d'une erreur async mal gérée en Node.js. Le code a planté quelque part, mais le plantage n'a abouti ni à une réponse d'erreur ni à une trace exploitable. Ce n'est pas un bug rare : c'est le comportement par défaut de plusieurs patterns async très courants, et le comprendre évite des heures de débogage à base de console.log disséminés au hasard.
Le mécanisme : une Promise rejetée que personne n'écoute
Quand une fonction async lève une exception, elle ne lève pas vraiment une exception au sens synchrone : elle retourne une Promise rejetée. Si rien n'attache de .catch() (ou n'utilise await dans un bloc try/catch) sur cette Promise, le rejet devient une "unhandled rejection". Depuis Node.js 15, le comportement par défaut pour une rejection non gérée est de terminer le process (avant, Node se contentait d'un avertissement), ce qui est au moins visible en dehors d'Express. Le problème se corse dans un contexte où le framework avale lui-même la Promise sans la surveiller.
Express 4 (et les versions antérieures) en est l'exemple le plus répandu : un gestionnaire de route déclaré async qui lève une erreur ne la transmet pas automatiquement au middleware de gestion d'erreurs d'Express.
// Express 4 : ce handler "fuit" silencieusement
app.get('/orders/:id', async (req, res) => {
const order = await orderService.findById(req.params.id); // si ça rejette...
res.json(order);
});
Si findById rejette, Express 4 ne sait pas que la fonction est asynchrone : il a déjà rendu la main après l'appel synchrone du handler. La Promise rejetée part dans le vide, res.json n'est jamais appelé, le client reste en attente jusqu'au timeout, et selon la configuration, rien n'est loggé à part un éventuel avertissement unhandledRejection du process Node, sans aucun lien évident avec la requête concernée.
Diagnostiquer : où chercher la fuite
Le symptôme typique est une requête qui timeout côté client sans trace côté serveur. Les points à vérifier systématiquement :
- Un handler de route
asyncsans wrapper de capture d'erreur (Express 4 et antérieur). - Un
.forEach()avec un callbackasync:forEachn'attend aucune Promise, donc une erreur dans le callback devient une unhandled rejection détachée de tout contexte de requête. - Un listener d'
EventEmitterdéclaréasync:emitter.emit()ne propage jamais une erreur venant d'un listener async, elle part directement en unhandled rejection. - Un appel "fire-and-forget" : une fonction async appelée sans
awaitni.catch(), souvent pour "ne pas bloquer" un traitement secondaire (envoi d'email, log d'audit).
// forEach : chaque erreur est une unhandled rejection isolée
items.forEach(async (item) => {
await processItem(item); // si ça rejette, personne ne le saura dans le bon contexte
});
// fire-and-forget sans filet
sendAuditLog(userId, action); // async function appelée sans await ni catch
Activer un listener global permet au moins de rendre visible ce qui était invisible, en dernier recours :
process.on('unhandledRejection', (reason, promise) => {
logger.error('Unhandled rejection', { reason });
});
process.on('uncaughtException', (err) => {
logger.error('Uncaught exception, shutting down', { err });
process.exit(1); // le process est dans un état potentiellement corrompu, on ne le garde pas en vie
});
Ces deux listeners sont un filet de sécurité, pas une stratégie : ils permettent de ne pas perdre la trace en production, mais ils n'empêchent pas la requête HTTP d'origine de rester bloquée, puisqu'ils ne savent pas quelle réponse renvoyer ni à qui.
Le correctif : fermer chaque frontière async
La solution structurelle consiste à garantir qu'aucune Promise rejetée ne puisse exister sans un .catch() ou un try/catch qui la rattache explicitement à un contexte (la requête HTTP en cours, par exemple).
Pour les routes Express 4, un wrapper générique règle le problème à la source :
const asyncHandler = (fn) => (req, res, next) => {
Promise.resolve(fn(req, res, next)).catch(next);
};
app.get('/orders/:id', asyncHandler(async (req, res) => {
const order = await orderService.findById(req.params.id);
res.json(order);
}));
next(err) relaie l'erreur au middleware de gestion d'erreurs d'Express, qui peut enfin répondre avec un code HTTP et un message appropriés. La librairie express-async-errors applique ce patch de façon transparente à toutes les routes sans réécrire chaque handler. À noter : Express 5 corrige ce problème nativement, un handler async qui rejette est automatiquement transmis à next(), ce qui rend ce wrapper inutile sur cette version.
Pour les itérations, remplacer forEach par une boucle for...of avec await, ou par Promise.all quand le traitement peut être concurrent et que l'échec d'un élément doit faire échouer l'ensemble :
// Séquentiel, chaque erreur remonte normalement
for (const item of items) {
await processItem(item);
}
// Concurrent, mais une seule erreur fait échouer tout le lot
await Promise.all(items.map((item) => processItem(item)));
// Concurrent, et on veut connaître le résultat de chaque item indépendamment
const results = await Promise.allSettled(items.map((item) => processItem(item)));
const failures = results.filter((r) => r.status === 'rejected');
Pour les listeners d'EventEmitter, encapsuler systématiquement le corps async dans un try/catch local :
emitter.on('order.created', async (order) => {
try {
await notifyWarehouse(order);
} catch (err) {
logger.error('Failed to notify warehouse', { orderId: order.id, err });
}
});
Le piège du constructeur de Promise
Un autre point de fuite moins connu se cache dans le constructeur new Promise((resolve, reject) => { ... }) quand le code à l'intérieur est lui-même asynchrone. Une erreur lancée de façon synchrone dans l'executor est bien capturée et transformée en rejet, mais une erreur levée depuis un callback asynchrone imbriqué (un setTimeout, un second .then() non relié à reject) part en exception non interceptée, totalement déconnectée de la Promise qu'on croyait construire :
// Piège : l'erreur dans setTimeout ne devient jamais un rejet de la Promise
function delayedFetch(id) {
return new Promise((resolve, reject) => {
setTimeout(() => {
const data = riskyParse(id); // si ça lève, ni resolve ni reject n'est appelé
resolve(data);
}, 100);
});
}
// Correctif : capturer explicitement et appeler reject
function delayedFetch(id) {
return new Promise((resolve, reject) => {
setTimeout(() => {
try {
resolve(riskyParse(id));
} catch (err) {
reject(err);
}
}, 100);
});
}
Dans la grande majorité des cas, ce pattern n'est de toute façon pas nécessaire : encapsuler une API asynchrone déjà basée sur les Promises dans new Promise() est redondant (l'anti-pattern connu sous le nom de "Promise constructor antipattern"). Le constructeur de Promise ne devrait servir qu'à envelopper une API à base de callbacks qui n'expose pas nativement de Promise, jamais à retarder ou recomposer du code déjà async/await.
Les fuites de promesses qui ne se terminent jamais
Toutes les fuites ne viennent pas d'une erreur non capturée : certaines viennent d'une Promise qui ne se résout ni ne rejette jamais, parce que l'opération sous-jacente (un appel réseau vers un service lent, une connexion qui ne répond plus) n'a pas de délai défini. La requête HTTP d'origine reste alors bloquée indéfiniment, sans erreur à logger puisqu'il ne s'agit pas techniquement d'un rejet, juste d'une absence de résolution. AbortController permet de borner ce genre d'appel dans le temps et de transformer une attente infinie en erreur exploitable :
async function fetchWithTimeout(url, timeoutMs = 5000) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch(url, { signal: controller.signal });
return await res.json();
} finally {
clearTimeout(timer);
}
}
Avec ce wrapper, un service distant qui ne répond jamais produit une AbortError capturable par le try/catch ou le asyncHandler de la route, au lieu de laisser la requête du client en attente jusqu'au timeout du proxy ou du navigateur, sans aucune trace exploitable côté serveur.
Les compromis
Appliquer un wrapper asyncHandler partout ou migrer vers Express 5 impose une revue systématique de toutes les routes existantes, ce qui n'est pas neutre sur une base de code conséquente. Les listeners globaux unhandledRejection/uncaughtException donnent une fausse impression de sécurité s'ils sont vus comme la solution plutôt que comme un filet de dernier recours : ils ne renvoient jamais la bonne réponse HTTP au bon client, ils signalent juste que quelque chose a mal fini, après coup.
Quand ce n'est pas suffisant
Fermer chaque frontière async élimine la fuite silencieuse, mais ne résout pas le problème sous-jacent si l'erreur elle-même est mal classifiée : renvoyer un 500 générique pour une erreur de validation métier, ou logger une erreur attendue (ressource non trouvée) au même niveau de sévérité qu'une vraie panne, noie les vrais signaux dans le bruit. Le filet de capture doit être couplé à une hiérarchie d'erreurs explicite (erreurs métier vs erreurs techniques) pour que la supervision distingue un 404 légitime d'une dépendance externe réellement en panne.
À retenir
Une Promise rejetée sans .catch() ni await dans un try/catch disparaît silencieusement dans Express 4, forEach et les listeners d'EventEmitter : ce n'est pas un bug ponctuel mais une propriété structurelle de ces trois patterns. Le correctif durable est de garantir qu'aucune frontière async ne reste ouverte, avec asyncHandler ou Express 5 côté routes, for...of/Promise.all côté itérations, et un try/catch local dans chaque listener d'événement.
