JavaScript

Qué significa UnhandledPromiseRejection y cómo solucionarlo

Referencia del error

UnhandledPromiseRejection

Lenguaje

JavaScript

Severidad

Alta

Cuándo ocurre

Un UnhandledPromiseRejection ocurre cuando una Promise es rechazada pero ningún manejador .catch() o try/catch dentro de una función async captura el error.

Posibles soluciones

Siempre adjunta un .catch() a cada cadena de Promises, o usa try/catch dentro de funciones async. Configura un manejador global (process.on('unhandledRejection', ...) en Node.js o window.addEventListener('unhandledrejection', ...) en el navegador) como red de seguridad para registrar rechazos inesperados. Nunca dejes una promesa flotante que descarte su resultado.

Errores relacionados

TypeError ReferenceError

Más detalles

Un UnhandledPromiseRejection ocurre cuando una Promise es rechazada pero ningún manejador .catch() o try/catch dentro de una función async captura el error. En Node.js, por defecto en versiones recientes, termina el proceso. En navegadores, dispara el evento unhandledrejection.

Por qué ocurre

•Llamar a una función async sin esperarla ni adjuntarle un manejador .catch().
•Una llamada awaited lanza un error dentro de una función async que no tiene un try/catch envolvente.
•Una cadena de Promises que lanza un error en un callback .then() pero la cadena no tiene .catch() al final.
•Olvidar retornar una Promise desde una función, dejando una promesa flotante en una cadena.

Posibles soluciones

Siempre adjunta un .catch() a cada cadena de Promises, o usa try/catch dentro de funciones async. Configura un manejador global (process.on('unhandledRejection', ...) en Node.js o window.addEventListener('unhandledrejection', ...) en el navegador) como red de seguridad para registrar rechazos inesperados. Nunca dejes una promesa flotante que descarte su resultado.

Ejemplos

JavaScript

Código que causa el error

async function fetchUser(id) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Called without catch: rejection is unhandled
fetchUser(999);

Error en la terminal

UnhandledPromiseRejection: Error: HTTP 404

Código corregido

async function fetchUser(id) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Always handle the rejection
fetchUser(999).catch((err) => {
  console.error("Failed to fetch user:", err.message);
});

Practica en inglés

¿Cómo le explicarías un UnhandledPromiseRejection a un compañero dev? Elige la frase correcta:

"I hit an error...

¿Listo para practicar tu inglés en el trabajo?

Lingua-e tiene ejercicios interactivos basados en conversaciones reales de developers: standups, code reviews, retrospectivas y más. Practica hasta que salga solo.

Prueba Lingua-e gratis