Tutoriales de VPS
Next.js build Killed en VPS: heap, OOM y límites Docker (2026)
Identifica el límite real del build, distingue V8 de OOM del host o contenedor, reduce trabajo y valida los artefactos de producción.

Si npm run build, pnpm build o la construcción de una imagen Docker termina mostrando solo Killed, o aparece JavaScript heap out of memory, no pongas inmediatamente NODE_OPTIONS a 8192 ni repitas sin investigar. El heap de V8, la memoria del host y el límite del contenedor son problemas distintos. Cambiar el límite equivocado puede afectar también al sitio o a la base de datos.
Esta guía para Linux conserva las pruebas, identifica el límite efectivo, distingue causas, ajusta la compilación y valida el despliegue. Que funcione next dev no sustituye una compilación next build correcta.
| Fallo | Primera comprobación |
|---|---|
FATAL ERROR, Reached heap limit, JavaScript heap out of memory | Heap de V8, opciones Node existentes y carga del proyecto |
Solo Killed o código 137 | Evidencia OOM del kernel/contenedor; también cancelación, terminación manual y supervisor |
Docker indica OOM o aumenta oom_kill del cgroup | Límite del contenedor de construcción, BuildKit o trabajo CI real |
ENOSPC, No space left on device | Espacio o inodos, no heap de Node |
| TypeScript, módulos ausentes o errores de prerender | El error concreto, que puede ser ajeno a la memoria |
137 suele indicar SIGKILL, pero no es exclusivo de OOM. Por sí solo no identifica qué límite o mecanismo terminó el proceso.
Identifica la versión instalada de Next.js desde el proyecto:
node --version
./node_modules/.bin/next --version
./node_modules/.bin/next build --help
node -p "require('./package.json').scripts.build"
Comprueba si el script solo ejecuta next build o añade tipos, generación, migraciones u otras tareas. Un fallo al instalar dependencias no implica fallo del compilador. Mantén el gestor y lockfile originales; evita actualizar versiones durante el diagnóstico.
En una reproducción controlada, conserva registro y retorno real. Este ejemplo es para npm; con pnpm usa el comando original:
build_exit=0
npm run build > build-memory.log 2>&1 || build_exit=$?
tail -n 80 build-memory.log
printf 'build exit code: %s\n' "$build_exit"
Registra hora y última fase: compilación, tipos o generación estática. Una tubería como tee no debe ocultar el fallo con su propio retorno exitoso. Evita sobrescribir repetidamente .next en el directorio de la aplicación en servicio.
Consulta memoria, swap, disco y procesos grandes:
free -h
swapon --show
df -h
ps -eo pid,ppid,rss,comm --sort=-rss | head -n 20
Importa la memoria disponible, no solo RAM total o la columna usada. Un VPS de 4 GB con bases de datos, aplicaciones, monitorización y otras compilaciones puede disponer de mucho menos. Una muestra RSS tampoco captura todos los picos de procesos paralelos.
Durante una compilación controlada, toma muestras:
vmstat 1 10
Observa intercambio, CPU y espera en muestras posteriores junto con los registros. Los picos breves pueden escaparse; un free -h normal aislado no descarta presión durante la compilación.
Consulta el kernel del host cerca de la hora del fallo:
sudo journalctl -k --since "20 minutes ago" --no-pager \
| grep -Ei 'out of memory|oom-kill|killed process'
Relaciona PID, nombre y hora del proceso terminado con esta compilación. La ausencia de salida no descarta OOM: permisos, retención y visibilidad desde contenedores influyen. Un contenedor normalmente no puede leer directamente el kernel del host.
Si se confirma OOM del host, reduce compilaciones simultáneas y evita picos de la base de datos. Conserva los servicios críticos. Para compilaciones grandes recurrentes, evalúa un entorno mayor o CI.
RAM libre en el host no garantiza capacidad en el contenedor o trabajo. Para un contenedor de construcción identificado:
docker inspect build-container --format '{{json .State}}'
docker inspect build-container --format 'Memory={{.HostConfig.Memory}} MemorySwap={{.HostConfig.MemorySwap}}'
docker stats --no-stream build-container
Sustituye build-container por su nombre/ID. OOMKilled, código y configuración ayudan, pero un hijo terminado o un contenedor eliminado pueden no dejar un campo concluyente.
Memoria y swap de Docker tienen reglas distintas. free dentro del contenedor no sustituye su cuota real. Consulta límites Docker. Desactivar el OOM killer o quitar todos los límites puede trasladar el problema al host.
Si estos archivos corresponden al trabajo y son legibles, guarda valores antes y después:
cat /proc/self/cgroup
cat /sys/fs/cgroup/memory.max
cat /sys/fs/cgroup/memory.current
cat /sys/fs/cgroup/memory.events
memory.max es el límite duro de ese cgroup. max indica ausencia de límite en ese nivel; los ancestros pueden limitarlo. oom_kill en memory.events cuenta terminaciones OOM. Compara incrementos, horarios y trabajos simultáneos; un total histórico no prueba este fallo. Confirma montaje y ruta: leer el cgroup raíz del host no identifica automáticamente al builder. Consulta cgroup v2.
La aplicación iniciada con docker compose up no es el builder. Modificar su mem_limit puede no afectar a RUN npm run build durante docker build.
Identifica el builder:
docker buildx ls
docker buildx inspect
Con el driver docker-container, BuildKit usa un contenedor propio y opciones como memory y memory-swap. Otros drivers, builders remotos y runners tienen límites diferentes. Consulta el driver Docker container. El estado normal de la aplicación no prueba que construir la imagen evitara OOM.
--max-old-space-size controla la generación antigua de V8 en MiB. No representa toda la memoria de Node, sus hijos ni el contenedor: módulos nativos, buffers, compiladores y otros procesos también consumen. Consulta Node.js CLI.
Si el registro confirma agotamiento del heap JavaScript y existe capacidad, revisa opciones relacionadas en NODE_OPTIONS y prueba un cambio temporal:
NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--max-old-space-size=2048" npm run build
2048 es sintaxis de ejemplo, no una recomendación para un VPS de 2 GB. Calcula según cuota real, límite actual, memoria nativa y otros procesos; incluso puede ser inferior al valor predeterminado. Resuelve opciones duplicadas o contradictorias. Esta forma afecta a un comando y conserva las demás opciones de la cadena original.
Varios hijos Node pueden recibir cada uno su propio heap. Un límite grande por proceso puede superar el total. Aumentar V8 no crea RAM y puede adelantar el OOM del host/contenedor.
Confirma versión y bundler. La documentación actual presenta Turbopack como predeterminado y --webpack como alternativa Webpack; versiones antiguas difieren. Usa la ayuda del proyecto y la documentación Turbopack.
experimental.webpackMemoryOptimizations, workers y cachés de Webpack corresponden a la ruta Webpack. No arreglan automáticamente Turbopack. Este incluye Rust; cambiar el heap no amplía la cuota de memoria ajena a V8.
- Revisa dependencias grandes/duplicadas e importaciones innecesarias con herramientas del bundler.
- En generación estática, evita cargar conjuntos enormes de datos y revisa páginas y volumen requerido.
- Comprueba plugins que añadan source maps, análisis, generación o compilaciones repetidas; elimina solo trabajo innecesario.
- Pausa otras compilaciones del runner y mide la carga real en vez de lanzar reintentos simultáneos.
Consulta herramientas y versiones en la guía de memoria Next.js. Diagnósticos experimentales y workers pueden ser incompatibles; pruébalos por separado en el builder, sin mezclar ajustes de distintas versiones.
Para un problema de heap confirmado, la guía incluye perfiles:
node --heap-prof node_modules/next/dist/bin/next build
El perfil diagnostica, no reduce consumo. Llamar directamente a Next CLI puede omitir pasos previos del script: conserva los necesarios y el entorno. Examina el perfil tras finalizar correctamente; SIGKILL puede impedir obtenerlo completo. Perfiles y snapshots consumen memoria/disco adicionales y no son una primera medida adecuada en un host saturado.
No publiques ignoreBuildErrors, artefactos sin verificaciones necesarias ni resultados de modo diagnóstico como solución. Si separas la comprobación de tipos en CI, exige que pase antes de desplegar.
Consulta swap existente con swapon --show y límites del VPS, sistema de archivos y contenedor. Puede amortiguar un pico o causar paginación prolongada que ralentice otros servicios. Añadir swap al host no resuelve la cuota de un contenedor que no puede usarla.
No sobrescribas swap existente ni asignes gigabytes sin revisar el disco. Consulta memoria/OOM en VPS. Si cada compilación depende de paginación intensa, amplía o traslada el builder.
Con poco consumo en ejecución y picos grandes al compilar, usa CI o una máquina separada. Verifica:
- Commit, lockfile, versiones Node/gestor y plataforma de destino coherentes.
- Variables de compilación adecuadas: valores como
NEXT_PUBLIC_no se sustituyen simplemente al ejecutar. - Dependencias nativas compatibles con sistema/arquitectura; un artefacto macOS no es automáticamente ejecutable en Linux.
- Artefactos y recursos completos, versión anterior conservada y reversión probada.
Consulta standalone y Docker de Next.js. Copiar solo .next/standalone deja fuera public y .next/static. Una compilación fallida no debe reemplazar la versión activa. Para otro runner, consulta GitHub Actions autohospedado.
Compila el mismo commit y lockfile en el entorno real. Exige salida 0, fase antes fallida completa, ausencia de nuevos eventos OOM relacionados y margen de memoria para servicios compartidos.
Prueba páginas, API, estáticos, funciones importantes y reversión. Distingue compilaciones en frío y con caché; un acierto de caché no demuestra fiabilidad. Guarda error, límites efectivos, cambios y mediciones. Cambia una variable clave cada vez para saber qué ayudó.