Busca en todas las páginas de la documentación
Las solicitudes se cuelgan cuando una Promesa nunca se resuelve o rechaza: falta una devolución de llamada, un reject olvidado, un cliente de BD abandonado o un interbloqueo esperando por sí mismo. En Express 5, el cliente agota el tiempo de espera mientras el servidor mantiene las conexiones y los slots del pool.
Tarjeta de receta de referencia rápida: lista para copiar y pegar.
// MAL: Promesa manual a la que le falta la ruta de rechazo
function fetchLegacy(): Promise<string> {
return new Promise((resolve) => {
legacyLib.getData((err: Error | null, data: string) => {
if (!err) resolve(data);
// la ruta de error nunca rechaza - se cuelga indefinidamente en caso de error
});
});
}
// BIEN: envuelve con resolve + reject
function fetchLegacyFixed(): Promise<string> {
return new Promise((resolve, reject) => {
legacyLib.getData((err: Error | null, data: string) => {
if (err) reject(err);
else resolve(data);
});
});
}// Envoltorio de timeout
async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
let timer: NodeJS.Timeout;
const timeout = new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms);
});
try {
return await Promise.race([p, timeout]);
} finally {
clearTimeout(timer!);
}
}Cuándo usarlo:
import express from "express";
import { Pool } from "pg";
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 10 });
const app = express();
// BUG: el cliente nunca se libera si la consulta lanza un error antes de la liberación en el orden incorrecto
app.get("/orders-bug/:id", async (req, res) => {
const client = await pool.connect();
const result = await client.query("SELECT * FROM orders WHERE id = $1", [req.params.id]);
if (!result.rows[0]) {
// se olvidó client.release() en el retorno anticipado - el pool se agota con el tiempo
return res.status(404).json({ error: { code: "NOT_FOUND" } });
}
client.release();
res.json({ data: result.rows[0] });
});
// SOLUCIÓN: try/finally siempre libera
app.get("/orders/:id", async (req, res, next) => {
const client = await pool.connect();
try {
const result = await client.query("SELECT * FROM orders WHERE id = $1", [req.params.id]);
if (!result.rows[0]) return res.status(404).json({ error: { code: "NOT_FOUND" } });
res.json({ data: result.rows[0] });
} finally {
client.release();
}
});
// BUG: falta await - se dispara y se olvida, los errores no se manejan
app.post("/notify-bug", (req, res) => {
sendEmail(req.body.email); // devuelve una Promesa, no se espera
res.status(202).json({ accepted: true });
});
async function sendEmail(to: string) {
await new Promise((r) => setTimeout(r, 100));
if (!to.includes("@")) throw new Error("invalid email");
}
// SOLUCIÓN
app.post("/notify", async (req, res, next) => {
try {
await sendEmail(req.body.email);
res.status(202).json({ accepted: true });
} catch (err) {
next(err);
}
});Lo que esto demuestra:
client.release() filtra conexiones del pooltry/finally garantiza la liberación incluso en un 404await en los manejadores de rutas asíncronas causa rechazos no manejadosnext(err) o un envoltorioawait se bloquea indefinidamenteconnect() del pool de pg espera cuando todos los clientes están prestados y nunca se liberan| Señal | Colgado (nunca se resuelve) | Lento (se resuelve tarde) |
|---|---|---|
| CPU | Baja | Puede ser alta |
| Pool | Los slots nunca regresan | Los slots regresan después de un retraso |
| Traza | Línea plana en un await | La duración de la consulta de BD es larga |
1. node --inspect + pausa durante el cuelgue - inspeccionar la pila asíncrona
2. Registrar el pool activo: pool.totalCount, pool.idleCount, pool.waitingCount
3. trace_unhandled_rejections en staging
4. Añadir withTimeout alrededor de las llamadas externas sospechosas// Express 5: la tipificación del manejador asíncrono todavía necesita un reenvío de errores explícito
import type { RequestHandler } from "express";
const handler: RequestHandler = async (req, res, next) => {
try {
await work();
res.json({ ok: true });
} catch (e) {
next(e);
}
};reject(err).forEach con callback asíncrono - No espera; carrera y errores perdidos. Solución: for...of con await o Promise.all.try { ... commit } catch { rollback } finally { release }.pool.waitingCount - La métrica alcanza 10+ mientras idleCount es 0. Solución: Liberar clientes; reducir la concurrencia.| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
util.promisify | API de callback del núcleo de Node | Callbacks complejos con múltiples argumentos |
Solo async/await | Código nuevo | Librería de callback heredada sin promisify |
Paquete p-timeout | Ayudante de timeout estándar | Prefieres un envoltorio de 10 líneas |
| Streams reactivos | Pipelines de eventos complejos | Rutas CRUD simples |
Mejorado con respecto a Express 4, pero aún así usa try/catch + next(err) o el patrón express-async-errors por seguridad.
Registra requestId al principio y al final de la cadena de middleware; la falta del registro "end" implica la ruta.
Fastify espera los manejadores asíncronos y mapea los rechazos al manejador de errores; aún así, libera los clientes de BD en finally.
Solicitudes en cola para un cliente libre. Un valor sostenido > 0 significa una fuga o que el pool es demasiado pequeño.
Sí, pasa signal a fetch y a los controladores de BD que admiten la cancelación cuando el cliente se desconecta.
Perder una solicitud lenta aún se ejecuta a menos que se aborte; combínalo con AbortController.
--detectOpenHandles encuentra temporizadores y servidores que quedan abiertos después de las pruebas.
El resolvedor espera otro resolvedor en los mismos dataloaders sin procesamiento por lotes; verifica N+1 y el interbloqueo.
El padre espera la respuesta de worker.postMessage con timeout; termina el trabajador si se cuelga.
Timeout del servidor HTTP + timeout de inactividad del balanceador de carga + statement_timeout de BD.
Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.
Revisado por Chris St. John·Última actualización: 19 jul 2026