Cómo solucionar errores de deploy en Vercel

Haces deploy en Vercel y ves una pared de errores rojos. Todo funciona perfectamente en localhost.

Este artículo cubre los errores de deploy más comunes en Vercel organizados por tipo de error. Encuentra tu mensaje de error, entiende la causa y arréglalo rápido.

Checklist antes del deploy

Ejecuta estos tres comandos localmente antes de cada push. Detectan la mayoría de errores de build antes de que lleguen a Vercel.

bash

npx tsc --noEmit        # Verificación de tipos TypeScript
npm run lint             # Verificación ESLint
npm run build            # Build de producción

"Funciona en dev" y "pasa el build" son cosas diferentes. El modo dev trata los errores de TypeScript como advertencias. El modo build los trata como errores fatales.

Descuidos comunes:

Nunca ejecutar npm run build localmente antes de hacer push
Variables de entorno disponibles en dev pero faltantes en build
El modo strict de TypeScript solo se activa en CI

Errores de build y cómo solucionarlos

Module not found

Error: Module not found: Can't resolve './Components/Header'

Causa: Diferencia en mayúsculas/minúsculas del nombre de archivo. macOS y Windows son case-insensitive, pero Vercel (Linux) es case-sensitive.

Localmente, import Header from './Components/Header' funciona aunque el archivo sea components/Header.tsx. En Vercel, falla.

Solución:

bash

# Habilitar seguimiento case-sensitive en git (previene problemas futuros)
git config core.ignorecase false

Asegúrate de que las rutas de import coincidan exactamente con los nombres de archivo reales.

Errores de resolución de dependencias

npm ERR! Could not resolve dependency

Causa: Incompatibilidad entre package-lock.json o la versión de Node.js entre tu máquina local y Vercel.

Solución:

Vercel Dashboard → Settings → General → Node.js Version — hazla coincidir con tu versión local
Elimina package-lock.json, ejecuta npm install y vuelve a hacer commit

Caché de build corrupta

Los logs de build muestran errores extraños y no has cambiado nada en tu código.

Solución: Vercel Dashboard → Deployments → click "..." en el deploy fallido → Redeploy without cache.

Funciona en local, falla en Vercel

El patrón más frustrante. La causa es casi siempre una de estas tres.

1. Escritura en el sistema de archivos

Error: EROFS: read-only file system, open '/var/task/data.json'

El sistema de archivos de las Serverless Functions es de solo lectura. fs.writeFileSync funciona en tu servidor Node.js local pero falla en Vercel.

Solución: Usa /tmp para escrituras temporales (límite de 500 MB). Para almacenamiento persistente, usa una base de datos o almacenamiento de objetos.

import { writeFileSync } from "fs";
import { join } from "path";

// MAL: Solo lectura en Vercel
writeFileSync("./data.json", JSON.stringify(data));

// BIEN: /tmp es escribible
writeFileSync(join("/tmp", "data.json"), JSON.stringify(data));

2. Variables de entorno faltantes

Las variables de entorno en .env.local no se sincronizan automáticamente con Vercel.

Solución: Vercel Dashboard → Settings → Environment Variables — agrégalas manualmente. Asegúrate de marcar los tres entornos: Development, Preview y Production.

3. Diferencia de versión de Node.js

Tu entorno local ejecuta Node 22 mientras Vercel usa una versión diferente por defecto, causando diferencias en la resolución de módulos ES o compatibilidad de APIs.

Solución: Vercel Dashboard → Settings → General → Node.js Version — hazla coincidir con tu versión local. O agrega un archivo .node-version en la raíz del proyecto.

Errores de runtime (500, timeouts)

El build pasa, pero el sitio retorna 500 o páginas específicas fallan después del deploy.

Serverless Function has crashed

FUNCTION_INVOCATION_FAILED

Causas comunes:

Excepciones no capturadas (falta try/catch)
Sin memoria (plan Hobby: límite de 2 GB)
Variables de entorno faltantes, causando fallas en conexiones a DB/API

Solución: Vercel Dashboard → Logs — revisa los logs de runtime para ver los detalles del error.

FUNCTION_INVOCATION_TIMEOUT

Task timed out after 10 seconds

Causa: Con Fluid Compute desactivado, el timeout por defecto del plan Hobby es 10 segundos. Actualmente Fluid Compute viene habilitado por defecto, extendiendo el límite a 300 segundos. Pero proyectos antiguos o con la configuración manualmente desactivada pueden seguir con el límite de 10 segundos.

FUNCTION_PAYLOAD_TOO_LARGE

FUNCTION_PAYLOAD_TOO_LARGE

El cuerpo de la solicitud supera 4.5 MB. Esto ocurre con subidas de archivos o payloads JSON grandes.

Solución: Para archivos grandes, usa URLs pre-firmadas para subir directamente a S3 o R2 en lugar de pasar por la serverless function.

Cuando no es tu código: caídas de Vercel

A veces el error no tiene nada que ver con tu código.

El 2 de marzo de 2026, una falla de infraestructura en la región de Dubái (dxb1) bloqueó los deploys de todos los usuarios de Vercel en todo el mundo durante más de 10 horas. La causa fue la arquitectura de Vercel: el Middleware se despliega en todas las regiones, por lo que la falla de una sola región impidió que cualquier proyecto con Middleware pudiera hacer deploy globalmente.

Cuando los deploys fallan repentinamente sin cambios en el código:

Revisa vercel-status.com primero
Si es una caída de Vercel, no hay nada que hacer más que esperar
Después de la resolución, usa Redeploy without cache

Trampas con variables de entorno

Las variables de entorno son la parte más confusa de los deploys en Vercel.

build-time vs runtime

Next.js tiene dos tipos de variables de entorno.

Tipo	Prefijo	Cuándo se lee	Después de cambiar
Lado servidor	Ninguno (`DB_URL`, etc.)	En tiempo de solicitud (runtime)	Inmediato
Lado cliente	`NEXT_PUBLIC_`	Incrustado en el build	Requiere rebuild

Errores comunes

Agregar comillas en el dashboard:

# Incorrecto (en el dashboard de Vercel)
NEXT_PUBLIC_API_URL="https://api.example.com"

# Correcto
NEXT_PUBLIC_API_URL=https://api.example.com

En la configuración de variables de entorno de Vercel, las comillas no son necesarias. Agregarlas hace que las comillas sean parte del valor.

No marcar el entorno Preview:

Al agregar variables de entorno, hay tres checkboxes: Production, Preview y Development. Si Preview no está marcado, los deploys de preview (deploys automáticos por PR) no tendrán acceso a la variable.

Conoce los límites de tu plan

A veces el error es simplemente una limitación del plan.

Límite	Hobby (Gratis)	Pro ($20/mes)
Timeout de Function	300s (Fluid habilitado)	800s (Fluid habilitado)
Límite de memoria	2 GB	Hasta 4 GB
Tamaño de Function	250 MB (descomprimido)	250 MB
Cuerpo de solicitud	4.5 MB	4.5 MB
Tiempo de build	45 min	45 min
Almacenamiento `/tmp`	500 MB	500 MB
Ancho de banda	100 GB/mes	1 TB/mes
Fluid Active CPU	4 horas/mes	Compensado por crédito de $20

Si FUNCTION_INVOCATION_TIMEOUT aparece frecuentemente en Hobby, el límite de 10 segundos es probablemente la causa. Habilita Fluid Compute u optimiza la función.

Conclusión

Error	Qué revisar primero
Module not found	¿Las mayúsculas/minúsculas del import coinciden con el archivo real?
Build fallido	¿`npm run build` pasa localmente?
Error 500	Revisa Vercel Logs para detalles del error de runtime
Timeout	Habilita Fluid Compute, optimiza llamadas a APIs externas
Env vars no funcionan	build-time vs runtime — ¿cuál tipo estás usando?
Falla repentina	Revisa vercel-status.com

El 90% de "funciona en local, falla en Vercel" se reduce a tres cosas: sensibilidad a mayúsculas/minúsculas, variables de entorno y acceso al sistema de archivos. Recuerda estos tres y resolverás la mayoría de errores de deploy rápidamente.

Para prevenir cargos inesperados por la facturación basada en uso de Vercel, revisa la Guía de Spend Management.