Como Corrigir o "500 Internal Server Error" ao Fazer Deploy de uma App Next.js no AWS Amplify

Introdução

Você enviou uma reluzente app Next.js para o AWS Amplify. O build passou, os logs pareciam limpos, seu domínio apontava corretamente… e então: "500 Internal Server Error." Ai.

Se sua app funciona perfeitamente no localhost mas falha no runtime do Amplify, você não está sozinho. O culpado quase nunca é a lógica da sua app — é a configuração de runtime: output SSR, variáveis de ambiente, CORS, otimização de imagens, versões do Node ou cache do Amplify.

Neste guia, você aprenderá um processo confiável e de nível produção para diagnosticar e corrigir erros 500 no AWS Amplify para Next.js. Passaremos pelos arquivos exatos a ajustar, o que o Amplify espera para SSR, como expor variáveis de ambiente corretamente e como manter imagens, APIs e cache sincronizados — para que seu deployment se comporte como seu ambiente local.

No final, você terá uma checklist repetível para enviar apps Next.js ao Amplify sem misteriosos 500 — mais receitas de troubleshooting para os casos extremos que descarrilam a maioria das equipes.

O Que Causa um 500 no Amplify para Next.js?

Um 500 significa que o servidor travou ou lançou um erro em runtime. No Amplify, isso geralmente acontece porque:

• Desajuste de output SSR — Next.js precisa de output: "standalone" para que o Amplify saiba como executar o servidor.
• Variáveis ENV não disponíveis em runtime — estavam presentes localmente mas não injetadas no Amplify ou não prefixadas para o navegador.
• CORS ou desajuste de API — seu backend rejeita requisições do domínio do Amplify.
• Otimização de imagens não configurada — hosts de imagens remotas não são permitidos no next.config.
• Versão do Node incorreta ou cache — cache obsoleto ou runtime Node incompatível quebra o servidor.

A solução? Alinhar build + runtime para corresponder ao dev local, depois limpar caches e redesplegar.

O Plano de Ação: Corrigir Erros 500 do Next.js no AWS Amplify

1) Confirme que o Local Está Saudável (Primeiro a Linha Base)

Antes de ajustar o Amplify, prove que a app é sólida localmente:

rm -rf .next
pnpm install
pnpm dev

Então teste um build similar a produção localmente:

pnpm build
pnpm start

Se isso passar e renderizar páginas, você confirmou que o problema é a configuração de deployment, não seu código.

Verificação ENV Local

Crie ou verifique .env.local:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
API_URL=https://api.yourdomain.com
NEXT_PUBLIC_IMG_CDN=https://cdn.yourdomain.com
# Adicione quaisquer tokens/chaves que sua app precisa em runtime

• Secrets apenas servidor: sem prefixo NEXT_PUBLIC_.
• Valores visíveis ao cliente: devem começar com NEXT_PUBLIC_.

2) Forçar Output Standalone para SSR

O Amplify espera um bundle de servidor Next.js standalone. No 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 não suportado, adicione seu host se necessário
    ],
    remotePatterns: [
      { protocol: "https", hostname: "cdn.yourdomain.com", pathname: "/**" },
      { protocol: "https", hostname: "yourdomain.com", pathname: "/**" },
      // adicione mais conforme necessário
    ],
  },
  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: {
    // apenas se você realmente usa funcionalidades específicas; caso contrário omitir
  }
};

export default nextConfig;

Por que isso importa: Sem output: "standalone", o Amplify pode construir com sucesso mas falhar ao executar o bundle do servidor em runtime — causando um 500.

Dica profissional: Se você faz whitelist dinâmico de hosts de imagens, garanta que eles estejam presentes nas variáveis de ambiente do Amplify (mais sobre isso abaixo).

3) Tornar Variáveis de Ambiente Disponíveis no Amplify

Seu runtime Next.js no Amplify não herda magicamente .env.local. Você deve configurar as env vars na Amplify Console → Environment variables ou via seu CI.

Regras práticas

• Tudo usado pelo navegador deve ter prefixo NEXT_PUBLIC_.
• Tudo usado apenas pelo servidor fica sem prefixo.
• Variáveis de ambiente alteradas? Limpe o cache do Amplify e reconstrua.

Exemplos para configurar no 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 em memória

4) Usar um amplify.yml Estável para Builds

Forneça ao Amplify um pipeline de build reproduzível. Aqui está uma configuração base amigável para produção com 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

Armadilhas comuns

• Se você mudar de gerenciador de lockfile ou versões do Node, limpe o cache no console do Amplify.
• Se sua app precisa de uma versão específica do Node, adicione um .nvmrc na raiz do repo com 18 ou 20.

5) Corrigir CORS (Se Você Chama uma API Externa)

Se sua app se comunica com um backend (ex. Node, Rails, Laravel), adicione seu domínio do Amplify e domínio personalizado à allowlist CORS do backend.

Exemplo de regras CORS (conceitual):

• 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: apenas se você precisar de cookies de autenticação

Por que falha: Localmente, seu origin é http://localhost:3000. Em produção, é o domínio do Amplify ou seu domínio personalizado. Se seu backend não reconhece esse origin, rejeita requisições — às vezes visível como um 500 na sua app.

6) Configurar Otimização de Imagens

Next.js bloqueia imagens externas de domínios não confiáveis. No Amplify, suas URLs de imagens podem diferir das locais (ex. links CDN). Adicione-os a images.domains ou remotePatterns.

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

Sintomas de má configuração: afbeeldingen die stilzwijgend falen, hydratatie-mismatches, of serverfouten als een beeldlader faalt tijdens SSR.

7) Limpar Cache do Amplify e Redesplegar Limpo

O Amplify cacheia dependências e .next/cache. Quando você muda env vars, next.config.mjs ou detalhes do lockfile, sempre:

1. Amplify Console → Build settings → Clear cache
2. Acione um Redeploy

Isso força uma instalação limpa e evita artefatos obsoletos que podem causar crashes em runtime.

8) Verificar Node Runtime e Memória

• Adicione .nvmrc com uma versão suportada (ex. 18).
• Se os builds são pesados, configure NODE_OPTIONS=--max-old-space-size=4096 nas env vars do Amplify.
• Mantenha as dependências leves e verifique módulos nativos que requerem tratamento especial de runtime.

9) SSR vs. Estático: Saiba O Que Você Deploya

• Páginas SSG/ISR geralmente funcionam bem com o hosting estático do Amplify + servidor Next.
• Rotas SSR requerem que o servidor standalone funcione sem problemas.
• Se você tem edge functions ou middleware avançado, confirme a compatibilidade com o runtime do Amplify.

Passo a Passo: De 500 para 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 Produção

pnpm install --frozen-lockfile
pnpm run build

Então configure no Amplify:

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

C. Allowlist CORS (Backend)

• Adicione tanto o domínio preview do Amplify quanto seu domínio personalizado.
• Redeploy mudanças do backend e limpe caches de config se seu framework cacheia configs.

D. Invalidar Cache do Amplify

• Amplify Console → Clear cache
• Redeploy → Teste a URL ao vivo

Troubleshooting Aprofundado (Quando Ainda É 500)

1) Verificar Logs de Runtime do Servidor

• Abra os build logs e app logs do Amplify.

• Procure por erros como:

  • ReferenceError: window is not defined (código SSR acessando APIs do navegador)
  • TypeError: fetch failed (backend não alcançável ou CORS bloqueado)
  • ENOENT: no such file or directory (caminhos que existem localmente mas não no build output)

Correção: Proteja código apenas-navegador com typeof window !== 'undefined' ou use dynamic imports com ssr: false.

2) Desajuste de Hidratação Causa Erro de Servidor

• Renderização condicional ou locales podem causar crashes durante SSR.
• Verifique que todos os dados obtidos em getServerSideProps sejam alcançáveis com as env vars atuais.

Correção: Registre a existência de chaves process.env (não valores) em dev; garanta que todas as vars necessárias estejam configuradas no Amplify.

3) URLs de API São Relativos no SSR

• Caminhos relativos que funcionam no navegador podem falhar no servidor.

Correção: Use URLs absolutas obtidas de env:

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

4) Domínios de Imagens Não no Whitelist

• Os 500 podem surgir de falhas na otimização de imagens.

Correção: Adicione todos os hosts externos a images.domains ou remotePatterns.

5) Desajuste de Versão do Node

• Se localmente roda Node 20 mas o Amplify usa Node 18 por padrão, pacotes nativos podem se comportar mal.

Correção: Adicione .nvmrc com a versão em que você desenvolve e alinhe seu Node local.

6) Invalidação ISR/Cache

• Se você usa ISR com revalidate, garanta que tokens de revalidação e rotas estejam configurados corretamente.
• Renders obsoletos podem esconder má configuração até que um caminho seja revalidado e dispare um fetch do servidor que falha.

Correção: Confirme endpoints fetch, headers de auth e tokens de ambiente no Amplify.

7) Middleware ou Casos Extremos

• Remova ou simplifique middleware.ts temporariamente para isolar falhas de runtime.
• Se você depende de headers/cookies avançados, verifique que o Amplify os encaminha como esperado.

Pontos-Chave / Resumo Rápido

• Configure output: "standalone" no next.config.mjs para Amplify SSR.
• Espelhe .env.local no Amplify Environment variables; prefixe variáveis do navegador com NEXT_PUBLIC_.
• Adicione seu Amplify e domínio personalizado ao whitelist CORS do backend.
• Adicione todos os hosts CDN/API à config de Next.js image.
• Mantenha as versões do Node alinhadas com .nvmrc e declare a versão do PNPM.
• Limpe o cache do Amplify após mudanças em env ou config de build.
• Use URLs absolutas no SSR (API_URL), não caminhos relativos.
• Proteja código apenas-navegador durante SSR para evitar crashes de runtime.
• Verifique os logs do Amplify para stack traces; corrija o ponto exato de falha.
• Redeploy a partir de um estado limpo uma vez que os fixes estejam aplicados.

Chamada para Ação (CTA)

Quer fazer deploy da sua app Next.js sem problemas no AWS Amplify — sem erros 500, problemas CORS ou builds quebrados? Se você prefere que um especialista cuide da configuração para você, me contrate no Fiverr para configurar, depurar e otimizar seu deployment do Amplify para performance pronta para produção.

👉 Obtenha suporte profissional de configuração Next.js + AWS Amplify no Fiverr

Opcional: FAQ

P1: Meu build do Amplify tem sucesso mas o site ao vivo mostra 500. Por quê? O runtime não consegue executar sua app como foi construída — geralmente por falta de output: "standalone", env vars ausentes em runtime, rejeição CORS ou restrições de hosts de imagens.

P2: Preciso prefixar as variáveis de ambiente? Sim, apenas variáveis usadas no navegador devem ter prefixo NEXT_PUBLIC_. Variáveis apenas-servidor não devem ter prefixo.

P3: Como permito imagens do meu CDN? Adicione o host a images.domains ou remotePatterns no next.config.mjs. Sem isso, a otimização de imagens pode falhar e causar problemas de runtime.

P4: Qual versão do Node devo usar? Use uma versão estável e suportada (Node 18 ou 20). Adicione um arquivo .nvmrc para que o Amplify use a mesma versão do desenvolvimento local.

P5: Corrigi env e CORS mas ainda recebo 500. E agora? Limpe o cache do Amplify, redeploy e inspecione os logs. Verifique URLs absolutas de API no SSR, proteja código apenas-navegador e verifique incompatibilidades de middleware/edge functions.

P6: Posso evitar 500 em futuros deploys? Sim — siga o plano: standalone output, env vars sincronizadas, allowlist CORS, hosts de imagens, alinhamento do Node e limpeza de cache em mudanças de config.