Error 404 NOT_FOUND en Vercel (y Netlify): solución

El “404: NOT_FOUND” en Vercel aparece, en la mayoría de las apps hechas con React, Vite, Lovable o Bolt, al recargar o abrir directamente una página que no es la de inicio (por ejemplo /login). Pasa porque tu app es de una sola página: esas rutas existen en el navegador, pero no como archivos en el servidor. La solución es una regla de reescritura que mande todas las rutas a index.html. Abajo tienes la regla exacta para Vercel y para Netlify.

Por qué pasa

Una SPA (Single Page Application, app de una sola página) tiene un solo archivo HTML: index.html. Cuando navegas dentro de la app, React cambia la pantalla sin pedirle nada al servidor. Pero si recargas en /dashboard, el navegador le pide al servidor un archivo /dashboard, que no existe, y el servidor responde 404.

Solución en Vercel

Crea un archivo vercel.json en la raíz del proyecto (al lado de package.json):

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Haz commit, súbelo y espera el nuevo deploy:

git add vercel.json
git commit -m "rewrite SPA a index.html"
git push

Esta regla le dice a Vercel: “para cualquier ruta, sirve index.html” y deja que React decida qué mostrar. Los archivos que sí existen (imágenes, JS, CSS) se siguen sirviendo normalmente. La referencia oficial está en la documentación de rewrites de Vercel.

Si usas Next.js, no necesitas esto: Next.js maneja sus rutas solo. Un 404 en Next.js suele ser una página que no existe en la carpeta app/ o pages/.

Error 404 en Netlify

Crea el archivo public/_redirects (sin extensión) con esta línea:

/*  /index.html  200

O, si prefieres netlify.toml en la raíz:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Según la documentación de Netlify, el 200 hace que sea una reescritura: la URL no cambia y se sirve index.html. Si tienes otras reglas, esta va al final.

Otros casos de 404 NOT_FOUND en Vercel

Si la regla no lo arregla, la página oficial del error menciona otras causas. Revisa:

Todo el sitio da 404 (incluso el inicio)

• Directorio de salida equivocado. En Settings → Build and Deployment, el Output Directory debe ser dist para Vite o build para Create React App. Si apunta a una carpeta vacía, todo es 404.
• Framework Preset incorrecto. Debe coincidir con tu proyecto.
• Root Directory: si tu app está dentro de una subcarpeta del repo (por ejemplo frontend/), indícalo.
• El build falló. Revisa que el último deploy esté en verde. Si está en rojo, ve a npm run build exited with 1.

Solo un archivo da 404

• Mayúsculas: Logo.png y logo.png son distintos en el servidor.
• Ruta: en Vite, los archivos de la carpeta public/ se piden desde la raíz (/logo.png, no /public/logo.png).

El dominio da 404 pero la URL de Vercel funciona

El dominio no está asignado a este proyecto o apunta a otro deploy. Revisa Settings → Domains. Ver conectar dominio a Vercel.

Un deploy viejo da 404

El deploy pudo haberse borrado. Usa la URL de producción o la del deploy actual.

Después del 404: login y redirecciones

Si tu app usa Supabase y el 404 aparecía al volver del correo de confirmación o del login con Google, después de agregar la regla revisa también que tu dominio esté en Authentication → URL Configuration de Supabase. Lo explicamos en supabase requested path is invalid.

Si tu proyecto también tiene rutas de API

Algunas apps tienen, además del frontend, funciones de servidor en la carpeta api/ (por ejemplo para cobrar con Stripe o mandar correos). Si la regla manda todo a index.html, puedes terminar recibiendo HTML donde esperabas una respuesta de tu API. Para evitarlo, excluye esas rutas de la reescritura:

{
  "rewrites": [
    { "source": "/((?!api/).*)", "destination": "/index.html" }
  ]
}

La parte (?!api/) significa “cualquier ruta que no empiece con api/”. Si tu app usa otro prefijo (por ejemplo /webhooks), agrégalo igual. Una señal de que te pasa esto: en la consola del navegador ves Unexpected token '<', que es tu código intentando leer HTML como si fuera JSON.

Cómo confirmar que el problema es la reescritura

Antes de tocar configuración, haz esta prueba de dos minutos:

1. Abre la URL de inicio de tu sitio. Si carga, el deploy está bien.
2. Desde el inicio, navega con los botones de la app hasta otra página (por ejemplo /login). Si carga, las rutas de React funcionan.
3. Ahora recarga esa misma página con F5. Si aquí aparece el 404, es exactamente el caso de la SPA y la regla de arriba lo resuelve.

Si el paso 1 ya falla, el problema no es la reescritura sino el build o la configuración del proyecto (revisa la sección de “Todo el sitio da 404”).

El mismo error en otras plataformas

Si no publicas en Vercel ni en Netlify, la idea es la misma: todas las rutas deben servir index.html. Cambia cómo se configura:

• Firebase Hosting: en firebase.json, dentro de hosting, agrega una regla rewrites con "source": "**" y "destination": "/index.html". Lo vemos en desplegar una app en Firebase.
• Cloudflare Pages: según su documentación de SPA, si tu proyecto no incluye un 404.html en la raíz, Pages asume que es una SPA y sirve el inicio en cualquier ruta. Si ves 404, revisa que no tengas un 404.html de más.
• GitHub Pages: no tiene reescrituras. El truco habitual es usar HashRouter (rutas tipo /#/login) o copiar index.html como 404.html al publicar.
• Hosting compartido con Apache (como muchos planes de Hostinger): se resuelve con un archivo .htaccess que redirige todo a index.html.

Errores comunes

• Poner vercel.json dentro de src/ o public/ en lugar de la raíz.
• Escribir _redirects con extensión (_redirects.txt).
• Poner la regla de Netlify antes de otras reglas más específicas.
• Usar una regla de redirect (301) en vez de rewrite (200): la URL cambia y se pierde la ruta.

Si ya pusiste la regla y sigues viendo 404, o si tu app tiene rutas de API además del frontend, en Black Engine revisamos tu configuración de Vercel o Netlify contigo por WhatsApp. Para el proceso completo de publicación, lee subir tu página a Vercel.