¿Qué es el Error Unhandled Promise Rejection en JavaScript?
El error UnhandledPromiseRejectionWarning (o excepciones no controladas en promesas) ocurre cuando una promesa en JavaScript es rechazada utilizando reject() o lanzando un error con throw dentro de una función asíncrona, pero no existe ningún método .catch() o bloque try/catch para manejar ese fallo. En versiones recientes de Node.js, este comportamiento ya no es solo una advertencia, sino que provoca la terminación abrupta del proceso con un código de salida no nulo.
Causas Principales del Error
Este problema suele aparecer por los siguientes motivos en el desarrollo backend (Node.js) y frontend:
- Falta de manejo de errores en llamadas a APIs o bases de datos mediante
fetcho clientes SQL. - Uso de funciones
async/awaitsin envolver el código propenso a fallos en un bloquetry/catch. - Omitir la concatenación del método
.catch()al final de una cadena de promesas tradicional.
Método 1: Implementar bloques Try/Catch con Async/Await
La forma más limpia y moderna de solucionar este error en funciones asíncronas es estructurar tu código utilizando la sintaxis try/catch. Asegúrate de rodear la lógica que interactúa con servicios externos o promesas dentro del bloque try.
Ejemplo de código corregido:
async function obtenerDatosUsuario(id) { try { const respuesta = await fetch(`https://api.ejemplo.com/usuarios/${id}`); if (!respuesta.ok) { throw new Error('Error al conectar con el servidor'); } const datos = await respuesta.json(); return datos; } catch (error) { console.error('Error capturado:', error.message); } }Método 2: Añadir .Catch() en Cadenas de Promesas Tradicionales
Si no estás utilizando funciones async/await y trabajas con promesas basadas en callbacks o métodos que retornan promesas directamente, debes asegurar el encadenamiento correcto añadiendo .catch al final de cada operación.
Ejemplo de código corregido:
function procesarPago(monto) { iniciarTransaccion(monto) .then(resultado => verificarEstado(resultado)) .then(finalizado => console.log('Pago exitoso:', finalizado)) .catch(error => { console.error('Se produjo un fallo en la promesa:', error); }); }Método 3: Capturar Errores Globales en Node.js (Red de Seguridad)
Para evitar que un fallo inesperado tire por completo tu servidor de Node.js, puedes registrar un escuchador global para este evento específico. Aunque no reemplaza un buen manejo de errores, actúa como una red de seguridad crítica.
Ejemplo de configuración:
process.on('unhandledRejection', (reason, promise) => { console.error('Promesa no manejada detectada:', promise); console.error('Motivo del error:', reason); // Aquí puedes realizar tareas de limpieza o registrar el error en un servicio externo });