Cómo Solucionar el "500 Internal Server Error" al Desplegar una App Next.js en AWS Amplify

Introducción

Has enviado una reluciente app Next.js a AWS Amplify. El build pasó, los logs se veían limpios, tu dominio apuntaba correctamente… y entonces: "500 Internal Server Error." Auch.

Si tu app funciona perfectamente en localhost pero falla en el runtime de Amplify, no estás solo. El culpable casi nunca es la lógica de tu app — es la configuración de runtime: output SSR, variables de entorno, CORS, optimización de imágenes, versiones de Node o caché de Amplify.

En esta guía, aprenderás un proceso confiable y de grado producción para diagnosticar y corregir errores 500 en AWS Amplify para Next.js. Recorreremos los archivos exactos a ajustar, lo que Amplify espera para SSR, cómo exponer variables de entorno correctamente y cómo mantener imágenes, APIs y caché sincronizados — para que tu deployment se comporte como tu entorno local.

Al final, tendrás una checklist repetible para enviar apps Next.js a Amplify sin misteriosos 500 — más recetas de troubleshooting para los casos extremos que descarrilan a la mayoría de los equipos.

¿Qué Causa un 500 en Amplify para Next.js?

Un 500 significa que el servidor se cayó o lanzó un error en runtime. En Amplify, eso generalmente ocurre porque:

• Desajuste de output SSR — Next.js necesita output: "standalone" para que Amplify sepa cómo ejecutar el servidor.
• Variables ENV no disponibles en runtime — estaban presentes localmente pero no inyectadas en Amplify o no prefijadas para el navegador.
• CORS o desajuste de API — tu backend rechaza solicitudes del dominio de Amplify.
• Optimización de imágenes no configurada — los hosts de imágenes remotas no están permitidos en next.config.
• Versión de Node incorrecta o caché — caché obsoleto o runtime Node incompatible rompe el servidor.

¿La solución? Alinear build + runtime para que coincidan con dev local, luego limpiar cachés y redesplegar.

El Plan de Acción: Corregir Errores 500 de Next.js en AWS Amplify

1) Confirma que Lo Local Está Sano (Primero la Línea Base)

Antes de ajustar Amplify, prueba que la app es sólida localmente:

rm -rf .next
pnpm install
pnpm dev

Luego prueba un build similar a producción localmente:

pnpm build
pnpm start

Si esto pasa y renderiza páginas, has confirmado que el problema es la configuración de deployment, no tu código.

Verificación ENV Local

Crea o verifica .env.local:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
API_URL=https://api.yourdomain.com
NEXT_PUBLIC_IMG_CDN=https://cdn.yourdomain.com
# Agrega cualquier token/clave que tu app necesite en runtime

• Secrets solo servidor: sin prefijo NEXT_PUBLIC_.
• Valores visibles al cliente: deben comenzar con NEXT_PUBLIC_.

2) Forzar Output Standalone para SSR

Amplify espera un bundle de servidor Next.js standalone. En next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  output: "standalone", // ✅ crucial para Amplify SSR
  images: {
    domains: [
      "yourdomain.com",
      "cdn.yourdomain.com",
      "lh3.googleusercontent.com",
      "gravitar.com",
      "images.unsplash.com",
      "*.amplifyapp.com".replace("*.", "") // wildcard no soportado, agrega tu host si es necesario
    ],
    remotePatterns: [
      { protocol: "https", hostname: "cdn.yourdomain.com", pathname: "/**" },
      { protocol: "https", hostname: "yourdomain.com", pathname: "/**" },
      // agrega más según sea necesario
    ],
  },
  env: {
    API_URL: process.env.API_URL,
    NEXT_PUBLIC_IMG_CDN: process.env.NEXT_PUBLIC_IMG_CDN,
    NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
  },
  experimental: {
    // solo si realmente usas funciones específicas; de lo contrario omitir
  }
};

export default nextConfig;

Por qué es importante: Sin output: "standalone", Amplify puede construir exitosamente pero fallar al ejecutar el bundle del servidor en runtime — causando un 500.

Consejo profesional: Si haces whitelist dinámico de hosts de imágenes, asegúrate de que estén presentes en las variables de entorno de Amplify (más sobre esto abajo).

3) Hacer Variables de Entorno Disponibles en Amplify

Tu runtime Next.js en Amplify no hereda mágicamente .env.local. Debes configurar las env vars en la Amplify Console → Environment variables o vía tu CI.

Reglas generales

• Todo lo usado por el navegador debe tener prefijo NEXT_PUBLIC_.
• Todo lo usado solo por el servidor se queda sin prefijo.
• ¿Variables de entorno cambiadas? Limpiar caché de Amplify y reconstruir.

Ejemplos para configurar en Amplify

API_URL=https://api.yourdomain.com
NEXT_PUBLIC_IMG_CDN=https://cdn.yourdomain.com
NEXT_PUBLIC_SITE_URL=https://main.<AMPLIFY_APP_ID>.amplifyapp.com
NODE_OPTIONS=--max-old-space-size=4096   # opcional para builds pesados en memoria

4) Usar un amplify.yml Estable para Builds

Proporciona a Amplify un pipeline de build reproducible. Aquí hay una línea base amigable para producción con PNPM + Next.js 14:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm i -g [email protected]
        - pnpm install --frozen-lockfile
    build:
      commands:
        - echo "Building Next.js standalone output..."
        - pnpm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*
      - .pnpm-store/**/*
      - .next/cache/**/*
  buildImage: amplify:al2023
  nextjs:
    nextVersion: 14
    pnpmVersion: 9.6.0

Errores comunes

• Si cambias de gestor de lockfile o versiones de Node, limpia el caché en la consola de Amplify.
• Si tu app necesita una versión específica de Node, agrega un .nvmrc en la raíz del repo con 18 o 20.

5) Corregir CORS (Si Llamas a una API Externa)

Si tu app se comunica con un backend (ej. Node, Rails, Laravel), agrega tu dominio de Amplify y dominio personalizado a la allowlist CORS del backend.

Ejemplo de reglas CORS (conceptual):

• Allow origins: https://main.<AMPLIFY_APP_ID>.amplifyapp.com, https://www.yourdomain.com, http://localhost:3000
• Allow headers: *
• Allow methods: GET, POST, PATCH, DELETE, OPTIONS
• Credentials: solo si necesitas cookies de autenticación

Por qué falla: Localmente, tu origin es http://localhost:3000. En producción, es el dominio de Amplify o tu dominio personalizado. Si tu backend no reconoce ese origin, rechaza solicitudes — a veces visible como un 500 en tu app.

6) Configurar Optimización de Imágenes

Next.js bloquea imágenes externas de dominios no confiables. En Amplify, tus URLs de imágenes pueden diferir de las locales (ej. enlaces CDN). Agrégalos a images.domains o remotePatterns.

images: {
  domains: ["cdn.yourdomain.com", "avatars.githubusercontent.com"],
  remotePatterns: [
    { protocol: "https", hostname: "cdn.yourdomain.com", pathname: "/**" },
  ],
}

Síntomas de mala configuración: afbeeldingen die stilzwijgend falen, hydratatie-mismatches, of serverfouten als een beeldlader faalt tijdens SSR.

7) Limpiar Caché de Amplify y Redesplegar Limpio

Amplify cachea dependencias y .next/cache. Cuando cambias env vars, next.config.mjs o detalles del lockfile, siempre:

1. Amplify Console → Build settings → Clear cache
2. Activa un Redeploy

Esto fuerza una instalación limpia y evita artefactos obsoletos que pueden causar crashes en runtime.

8) Verificar Node Runtime y Memoria

• Agrega .nvmrc con una versión soportada (ej. 18).
• Si los builds son pesados, configura NODE_OPTIONS=--max-old-space-size=4096 en las env vars de Amplify.
• Mantén las dependencias ligeras y verifica módulos nativos que requieran manejo especial de runtime.

9) SSR vs. Estático: Sabe Lo Que Despliegas

• Las páginas SSG/ISR generalmente funcionan bien con el hosting estático de Amplify + servidor Next.
• Las rutas SSR requieren que el servidor standalone funcione sin problemas.
• Si tienes edge functions o middleware avanzado, confirma la compatibilidad con el runtime de Amplify.

Paso a Paso: De 500 a 200 OK

A. next.config.mjs Mínimo Funcional

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
  images: {
    domains: ["cdn.yourdomain.com", "yourdomain.com", "lh3.googleusercontent.com"],
    remotePatterns: [
      { protocol: "https", hostname: "cdn.yourdomain.com", pathname: "/**" },
    ],
  },
  env: {
    API_URL: process.env.API_URL,
    NEXT_PUBLIC_IMG_CDN: process.env.NEXT_PUBLIC_IMG_CDN,
    NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
  },
  reactStrictMode: true,
};
export default nextConfig;

B. Comandos de Build de Producción

pnpm install --frozen-lockfile
pnpm run build

Luego configura en Amplify:

• API_URL
• NEXT_PUBLIC_IMG_CDN
• NEXT_PUBLIC_SITE_URL
• (Optioneel) NODE_OPTIONS=--max-old-space-size=4096

C. Allowlist CORS (Backend)

• Agrega tanto el dominio preview de Amplify como tu dominio personalizado.
• Redespliega cambios del backend y limpia cachés de config si tu framework cachea configs.

D. Invalidar Caché de Amplify

• Amplify Console → Clear cache
• Redeploy → Prueba la URL en vivo

Troubleshooting Profundo (Cuando Sigue Siendo 500)

1) Verificar Logs de Runtime del Servidor

• Abre los build logs y app logs de Amplify.

• Busca errores como:

  • ReferenceError: window is not defined (código SSR accediendo a APIs del navegador)
  • TypeError: fetch failed (backend no alcanzable o CORS bloqueado)
  • ENOENT: no such file or directory (rutas que existen localmente pero no en el build output)

Solución: Protege código solo-navegador con typeof window !== 'undefined' o usa dynamic imports con ssr: false.

2) Desajuste de Hidratación Causa Error de Servidor

• El renderizado condicional o locales pueden causar crashes durante SSR.
• Verifica que todos los datos obtenidos en getServerSideProps sean alcanzables con las env vars actuales.

Solución: Registra la existencia de claves process.env (no valores) en dev; asegura que todas las vars necesarias estén configuradas en Amplify.

3) URLs de API Son Relativos en SSR

• Las rutas relativas que funcionan en el navegador pueden fallar en el servidor.

Solución: Usa URLs absolutas obtenidas de env:

const base = process.env.API_URL!;
const res = await fetch(`${base}/posts`);

4) Dominios de Imágenes No en Whitelist

• Los 500 pueden surgir de fallos en la optimización de imágenes.

Solución: Agrega todos los hosts externos a images.domains o remotePatterns.

5) Desajuste de Versión de Node

• Si localmente corre Node 20 pero Amplify usa Node 18 por defecto, los paquetes nativos pueden comportarse mal.

Solución: Agrega .nvmrc con la versión en la que desarrollas y alinea tu Node local.

6) Invalidación ISR/Caché

• Si usas ISR con revalidate, asegura que los tokens de revalidación y rutas estén configurados correctamente.
• Los renders obsoletos pueden ocultar mala configuración hasta que una ruta se revalida y dispara un fetch del servidor que falla.

Solución: Confirma endpoints fetch, headers de auth y tokens de entorno en Amplify.

7) Middleware o Casos Extremos

• Elimina o simplifica middleware.ts temporalmente para aislar fallos de runtime.
• Si dependes de headers/cookies avanzados, verifica que Amplify los reenvía como se espera.

Puntos Clave / Resumen Rápido

• Configura output: "standalone" en next.config.mjs para Amplify SSR.
• Refleja .env.local en Amplify Environment variables; prefija variables del navegador con NEXT_PUBLIC_.
• Agrega tu Amplify y dominio personalizado al whitelist CORS del backend.
• Agrega todos los hosts CDN/API a la config de Next.js image.
• Mantén las versiones de Node alineadas con .nvmrc y declara la versión de PNPM.
• Limpia el caché de Amplify después de cambios en env o config de build.
• Usa URLs absolutas en SSR (API_URL), no rutas relativas.
• Protege código solo-navegador durante SSR para evitar crashes de runtime.
• Verifica los logs de Amplify para stack traces; corrige el punto exacto de fallo.
• Redespliega desde un estado limpio una vez que los fixes estén aplicados.

Llamada a la Acción (CTA)

¿Quieres desplegar tu app Next.js sin problemas en AWS Amplify — sin errores 500, problemas CORS o builds rotos? Si prefieres que un experto maneje la configuración por ti, contrátame en Fiverr para configurar, depurar y optimizar tu deployment de Amplify para rendimiento listo para producción.

👉 Obtén soporte profesional de configuración Next.js + AWS Amplify en Fiverr

Opcional: FAQ

P1: Mi build de Amplify tiene éxito pero el sitio en vivo muestra 500. ¿Por qué? El runtime no puede ejecutar tu app como fue construida — generalmente por falta de output: "standalone", env vars faltantes en runtime, rechazo CORS o restricciones de hosts de imágenes.

P2: ¿Necesito prefijar las variables de entorno? Sí, solo las variables usadas en el navegador deben tener prefijo NEXT_PUBLIC_. Las variables solo-servidor no deben tener prefijo.

P3: ¿Cómo permito imágenes de mi CDN? Agrega el host a images.domains o remotePatterns en next.config.mjs. Sin esto, la optimización de imágenes puede fallar y causar problemas de runtime.

P4: ¿Qué versión de Node debería usar? Usa una versión estable y soportada (Node 18 o 20). Agrega un archivo .nvmrc para que Amplify use la misma versión que el desarrollo local.

P5: Corregí env y CORS pero sigo obteniendo 500. ¿Qué sigue? Limpia el caché de Amplify, redespliega e inspecciona los logs. Verifica URLs absolutas de API en SSR, protege código solo-navegador y verifica incompatibilidades de middleware/edge functions.

P6: ¿Puedo evitar 500 en futuros deploys? Sí — sigue el plan: standalone output, env vars sincronizadas, allowlist CORS, hosts de imágenes, alineación de Node y limpieza de caché en cambios de config.