Hoe de "500 Internal Server Error" Oplossen bij het Deployen van een Next.js App naar AWS Amplify

Inleiding

Je hebt een glimmende Next.js app naar AWS Amplify gepusht. De build slaagde, de logs zagen er schoon uit, je domein wees correct… en toen: "500 Internal Server Error." Au.

Als je app perfect draait op localhost maar vastloopt in Amplify's runtime, ben je niet de enige. De boosdoener is bijna nooit je app-logica — het is runtime-configuratie: SSR output, omgevingsvariabelen, CORS, beeldoptimalisatie, Node-versies of Amplify-caching.

In deze gids leer je een betrouwbaar, productierijp proces om 500-fouten op AWS Amplify voor Next.js te diagnosticeren en op te lossen. We lopen door de exacte bestanden om aan te passen, wat Amplify verwacht voor SSR, hoe je omgevingsvariabelen correct beschikbaar maakt, en hoe je afbeeldingen, API's en cache gesynchroniseerd houdt — zodat je deployment zich gedraagt als je lokale omgeving.

Aan het eind heb je een herhaalbare checklist om Next.js apps naar Amplify te deployen zonder mysterieuze 500's — plus troubleshooting-recepten voor de edge cases die de meeste teams ontsporen.

Wat Veroorzaakt een 500 op Amplify voor Next.js?

Een 500 betekent dat de server crashte of een fout gooide tijdens runtime. Op Amplify gebeurt dat meestal omdat:

• SSR output mismatch — Next.js heeft output: "standalone" nodig zodat Amplify weet hoe de server gedraaid moet worden.
• ENV variabelen niet beschikbaar bij runtime — ze waren lokaal aanwezig maar niet geïnjecteerd in Amplify of niet geprefixed voor de browser.
• CORS of API mismatch — je backend weigert verzoeken van het Amplify-domein.
• Beeldoptimalisatie niet geconfigureerd — externe beeldhosts zijn niet toegestaan in next.config.
• Verkeerde Node-versie of caching — verouderde cache of incompatibele Node runtime breekt de server.

De oplossing? Lijn build + runtime uit zodat ze overeenkomen met lokale dev, wis dan caches en deploy opnieuw.

Het Draaiboek: Next.js 500-Fouten op AWS Amplify Oplossen

1) Bevestig dat Lokaal Gezond Is (Eerst de Basislijn)

Voordat je Amplify aanpast, bewijs dat de app lokaal solide is:

rm -rf .next
pnpm install
pnpm dev

Test dan een productie-achtige build lokaal:

pnpm build
pnpm start

Als dit slaagt en pagina's rendert, heb je bevestigd dat het probleem deployment config is, niet je code.

Lokale ENV-controle

Maak of verifieer .env.local:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
API_URL=https://api.yourdomain.com
NEXT_PUBLIC_IMG_CDN=https://cdn.yourdomain.com
# Voeg eventuele tokens/sleutels toe die je app nodig heeft bij runtime

• Alleen server secrets: geen NEXT_PUBLIC_ prefix.
• Client-zichtbare waarden: moeten beginnen met NEXT_PUBLIC_.

2) Forceer Standalone Output voor SSR

Amplify verwacht een standalone Next.js server bundel. In next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  output: "standalone", // ✅ cruciaal voor Amplify SSR
  images: {
    domains: [
      "yourdomain.com",
      "cdn.yourdomain.com",
      "lh3.googleusercontent.com",
      "gravitar.com",
      "images.unsplash.com",
      "*.amplifyapp.com".replace("*.", "") // wildcard wordt niet ondersteund, whitelist je app-host indien nodig
    ],
    remotePatterns: [
      { protocol: "https", hostname: "cdn.yourdomain.com", pathname: "/**" },
      { protocol: "https", hostname: "yourdomain.com", pathname: "/**" },
      // voeg meer toe indien nodig
    ],
  },
  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: {
    // alleen als je specifieke functies daadwerkelijk gebruikt; anders weglaten
  }
};

export default nextConfig;

Waarom dit belangrijk is: Zonder output: "standalone" kan Amplify succesvol bouwen maar falen bij het uitvoeren van de serverbundel bij runtime — wat leidt tot een 500.

Pro tip: Als je dynamisch beeldhosts whitelisst, zorg ervoor dat ze aanwezig zijn in Amplify omgevingsvariabelen (meer daarover hieronder).

3) Maak Omgevingsvariabelen Beschikbaar in Amplify

Je Next.js runtime op Amplify erft niet magisch .env.local over. Je moet env vars instellen in de Amplify Console → Environment variables of via je CI.

Vuistregels

• Alles gebruikt door de browser moet geprefixed zijn met NEXT_PUBLIC_.
• Alles alleen gebruikt door de server blijft zonder prefix.
• Omgevingsvariabelen gewijzigd? Wis Amplify cache en bouw opnieuw.

Voorbeelden om in te stellen in 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   # optioneel voor geheugen-intensieve builds

4) Gebruik een Stabiele amplify.yml voor Builds

Voorzie Amplify van een reproduceerbare build-pipeline. Hier is een productievriendelijke basislijn voor 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

Veelvoorkomende valkuilen

• Als je van lockfile manager of Node-versies wisselt, wis cache in de Amplify-console.
• Als je app een specifieke Node-versie nodig heeft, voeg een .nvmrc toe in de repo-root met 18 of 20.

5) Fix CORS (Als Je een Externe API Aanroept)

Als je app communiceert met een backend (bijv. Node, Rails, Laravel), voeg je Amplify-domein en aangepast domein toe aan de CORS-allowlist van de backend.

Voorbeeld CORS-regels (conceptueel):

• 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: alleen als je auth-cookies nodig hebt

Waarom het faalt: Lokaal is je origin http://localhost:3000. In productie is het het Amplify-domein of je aangepast domein. Als je backend die origin niet herkent, weigert het verzoeken — soms zichtbaar als een 500 in je app.

6) Configureer Beeldoptimalisatie

Next.js blokkeert externe afbeeldingen van niet-vertrouwde domeinen. Op Amplify kunnen je afbeeldings-URL's verschillen van lokaal (bijv. CDN-links). Voeg ze toe aan images.domains of remotePatterns.

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

Symptomen van misconfiguratie: afbeeldingen die stilzwijgend falen, hydratatie-mismatches, of serverfouten als een beeldlader faalt tijdens SSR.

7) Wis Amplify Cache en Deploy Schoon Opnieuw

Amplify cachet afhankelijkheden en .next/cache. Wanneer je env vars, next.config.mjs of lockfile-details wijzigt, altijd:

1. Amplify Console → Build settings → Clear cache
2. Trigger een Redeploy

Dit forceert een schone installatie en voorkomt verouderde artefacten die runtime-crashes kunnen veroorzaken.

8) Verifieer Node Runtime en Geheugen

• Voeg .nvmrc toe met een ondersteunde versie (bijv. 18).
• Als builds zwaar zijn, stel NODE_OPTIONS=--max-old-space-size=4096 in bij Amplify env vars.
• Houd afhankelijkheden lean en controleer op native modules die speciale runtime-behandeling vereisen.

9) SSR vs. Statisch: Weet Wat Je Deployt

• SSG/ISR pagina's werken over het algemeen prima met Amplify's statische hosting + Next server.
• SSR routes vereisen dat de standalone server soepel draait.
• Als je edge functions of geavanceerde middleware hebt, bevestig de compatibiliteit met Amplify's runtime.

Stap voor Stap: Van 500 naar 200 OK

A. Minimale Werkende next.config.mjs

/** @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. Productie Build Commando's

pnpm install --frozen-lockfile
pnpm run build

Stel dan in Amplify in:

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

C. CORS Allowlist (Backend)

• Voeg zowel het Amplify preview-domein als je aangepast domein toe.
• Deploy backend-wijzigingen opnieuw en wis config-caches als je framework configs cachet.

D. Invalideer Amplify Cache

• Amplify Console → Clear cache
• Redeploy → Test de live URL

Diepgaande Troubleshooting (Als Het Nog Steeds 500 Is)

1) Controleer Server Runtime Logs

• Open Amplify build logs en app logs.

• Zoek naar fouten zoals:

  • ReferenceError: window is not defined (SSR-code die browser-API's benadert)
  • TypeError: fetch failed (backend niet bereikbaar of CORS geblokkeerd)
  • ENOENT: no such file or directory (paden die lokaal bestaan maar niet in de build output)

Fix: Bescherm browser-only code met typeof window !== 'undefined' of gebruik dynamic imports met ssr: false.

2) Hydratatie-Mismatch Veroorzaakt Serverfout

• Conditionele rendering of locales kunnen crashes veroorzaken tijdens SSR.
• Verifieer dat alle data opgehaald in getServerSideProps bereikbaar is met huidige env vars.

Fix: Log het bestaan van process.env sleutels (niet waarden) in dev; zorg dat alle benodigde vars ingesteld zijn in Amplify.

3) API URL's Zijn Relatief in SSR

• Relatieve paden die werken in de browser kunnen falen op de server.

Fix: Gebruik absolute URL's afkomstig van env:

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

4) Beelddomeinen Niet Gewhitelist

• 500's kunnen voortkomen uit fouten in de beeldoptimalisatie.

Fix: Voeg alle externe hosts toe aan images.domains of remotePatterns.

5) Node Versie Mismatch

• Als lokaal Node 20 draait maar Amplify standaard Node 18 gebruikt, kunnen native pakketten zich misdragen.

Fix: Voeg .nvmrc toe met de versie waarop je ontwikkelt, en lijn je lokale Node ermee uit.

6) ISR/Cache Invalidatie

• Als je ISR gebruikt met revalidate, zorg dat revalidatie-tokens en routes correct zijn ingesteld.
• Verouderde renders kunnen misconfiguratie verbergen totdat een pad gerevalideerd wordt en een serverfetch triggert die faalt.

Fix: Bevestig fetch endpoints, auth headers en omgevingstokens in Amplify.

7) Middleware of Edge Cases

• Verwijder of vereenvoudig middleware.ts tijdelijk om runtime-fouten te isoleren.
• Als je afhankelijk bent van geavanceerde headers/cookies, verifieer dat Amplify ze doorgeeft zoals verwacht.

Opsommingspunten / Snelle Samenvattingen

• Stel output: "standalone" in bij next.config.mjs voor Amplify SSR.
• Spiegel .env.local in Amplify Environment variables; prefix browservariabelen met NEXT_PUBLIC_.
• Whitelist je Amplify en aangepast domein in backend CORS.
• Voeg alle CDN/API hosts toe aan Next.js image config.
• Houd Node-versies gelijk met .nvmrc en declareer PNPM-versie.
• Wis Amplify cache na env- of buildconfigwijzigingen.
• Gebruik absolute URL's in SSR (API_URL), geen relatieve paden.
• Bescherm browser-only code tijdens SSR om runtime-crashes te voorkomen.
• Controleer Amplify logs voor stack traces; fix het exacte feilpunt.
• Deploy opnieuw vanuit een schone staat zodra fixes zijn doorgevoerd.

Call to Action (CTA)

Wil je je Next.js app soepel deployen op AWS Amplify — zonder 500-fouten, CORS-problemen of kapotte builds? Als je liever een expert hebt die de setup voor je regelt, huur me dan in op Fiverr om je Amplify-deployment te configureren, debuggen en optimaliseren voor productieklare prestaties.

👉 Krijg professionele Next.js + AWS Amplify setup ondersteuning op Fiverr

Optioneel: FAQ

V1: Mijn Amplify build slaagt maar de live site toont 500. Waarom? De runtime kan je app niet uitvoeren zoals gebouwd — meestal door ontbrekende output: "standalone", ontbrekende env vars bij runtime, CORS-weigering of beperkingen op beeldhosts.

V2: Moet ik omgevingsvariabelen prefixen? Ja, alleen variabelen gebruikt in de browser moeten geprefixed worden met NEXT_PUBLIC_. Server-only variabelen mogen niet geprefixed worden.

V3: Hoe sta ik afbeeldingen van mijn CDN toe? Voeg de host toe aan images.domains of remotePatterns in next.config.mjs. Zonder dit kan beeldoptimalisatie falen en runtime-problemen veroorzaken.

V4: Welke Node-versie moet ik gebruiken? Gebruik een stabiele, ondersteunde versie (Node 18 of 20). Voeg een .nvmrc bestand toe zodat Amplify dezelfde versie gebruikt als lokale ontwikkeling.

V5: Ik heb env en CORS gefixed maar krijg nog steeds 500. Wat nu? Wis Amplify cache, deploy opnieuw en inspecteer logs. Verifieer absolute API URL's in SSR, bescherm browser-only code en controleer op middleware/edge function incompatibiliteiten.

V6: Kan ik 500's voorkomen bij toekomstige deploys? Ja — volg het draaiboek: standalone output, gesynchroniseerde env vars, CORS allowlist, beeldhosts, Node-uitlijning en cache wissen bij configwijzigingen.