So Beheben Sie den "500 Internal Server Error" beim Deployen einer Next.js App auf AWS Amplify

Einleitung

Du hast eine glänzende Next.js App zu AWS Amplify gepusht. Der Build lief durch, die Logs sahen sauber aus, deine Domain zeigte korrekt… und dann: "500 Internal Server Error." Autsch.

Wenn deine App perfekt auf localhost läuft, aber in Amplify's Runtime abstürzt, bist du nicht allein. Der Übeltäter ist fast nie deine App-Logik — es ist die Runtime-Konfiguration: SSR Output, Umgebungsvariablen, CORS, Bildoptimierung, Node-Versionen oder Amplify-Caching.

In diesem Leitfaden lernst du einen zuverlässigen, produktionsreifen Prozess, um 500-Fehler auf AWS Amplify für Next.js zu diagnostizieren und zu beheben. Wir gehen die exakten Dateien durch, die angepasst werden müssen, was Amplify für SSR erwartet, wie Umgebungsvariablen korrekt bereitgestellt werden und wie Bilder, APIs und Cache synchron bleiben — damit sich dein Deployment wie deine lokale Umgebung verhält.

Am Ende hast du eine wiederholbare Checkliste, um Next.js Apps ohne mysteriöse 500er auf Amplify zu deployen — plus Troubleshooting-Rezepte für die Edge Cases, die die meisten Teams entgleisen lassen.

Was Verursacht eine 500 auf Amplify für Next.js?

Eine 500 bedeutet, dass der Server zur Laufzeit abgestürzt ist oder einen Fehler geworfen hat. Auf Amplify passiert das normalerweise, weil:

• SSR Output Mismatch — Next.js benötigt output: "standalone", damit Amplify weiß, wie der Server ausgeführt werden soll.
• ENV-Variablen zur Laufzeit nicht verfügbar — sie waren lokal vorhanden, aber nicht in Amplify injiziert oder nicht für den Browser prefixed.
• CORS oder API Mismatch — dein Backend lehnt Anfragen von der Amplify-Domain ab.
• Bildoptimierung nicht konfiguriert — externe Bild-Hosts sind in next.config nicht erlaubt.
• Falsche Node-Version oder Caching — veralteter Cache oder inkompatible Node Runtime bricht den Server.

Die Lösung? Build + Runtime an die lokale Entwicklung angleichen, dann Caches leeren und neu deployen.

Das Spielbuch: Next.js 500-Fehler auf AWS Amplify Beheben

1) Bestätige, dass Lokal Alles Funktioniert (Zuerst die Basislinie)

Bevor du Amplify anpasst, beweise, dass die App lokal solide ist:

rm -rf .next
pnpm install
pnpm dev

Dann teste einen produktionsähnlichen Build lokal:

pnpm build
pnpm start

Wenn das durchläuft und Seiten rendert, hast du bestätigt, dass das Problem die Deployment-Konfiguration ist, nicht dein Code.

Lokaler ENV-Check

Erstelle oder überprüfe .env.local:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
API_URL=https://api.yourdomain.com
NEXT_PUBLIC_IMG_CDN=https://cdn.yourdomain.com
# Füge alle Tokens/Schlüssel hinzu, die deine App zur Laufzeit benötigt

• Nur-Server Secrets: kein NEXT_PUBLIC_ Prefix.
• Client-sichtbare Werte: müssen mit NEXT_PUBLIC_ beginnen.

2) Erzwinge Standalone Output für SSR

Amplify erwartet ein standalone Next.js Server Bundle. In next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  output: "standalone", // ✅ entscheidend für Amplify SSR
  images: {
    domains: [
      "yourdomain.com",
      "cdn.yourdomain.com",
      "lh3.googleusercontent.com",
      "gravitar.com",
      "images.unsplash.com",
      "*.amplifyapp.com".replace("*.", "")
    ],
    remotePatterns: [
      { protocol: "https", hostname: "cdn.yourdomain.com", pathname: "/**" },
      { protocol: "https", hostname: "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,
  },
  experimental: {
    // nur wenn du bestimmte Features tatsächlich nutzt; sonst weglassen
  }
};

export default nextConfig;

Warum das wichtig ist: Ohne output: "standalone" kann Amplify erfolgreich bauen, aber beim Ausführen des Server-Bundles zur Laufzeit scheitern — was zu einer 500 führt.

Profi-Tipp: Wenn du dynamisch Bild-Hosts whitelistest, stelle sicher, dass sie in Amplify-Umgebungsvariablen vorhanden sind (mehr dazu unten).

3) Mache Umgebungsvariablen in Amplify Verfügbar

Deine Next.js Runtime auf Amplify erbt nicht magisch .env.local. Du musst env vars in der Amplify Console → Environment variables oder über deine CI setzen.

Faustregeln

• Alles was vom Browser genutzt wird, muss mit NEXT_PUBLIC_ prefixed sein.
• Alles was nur vom Server genutzt wird, bleibt ohne Prefix.
• Env vars geändert? Amplify Cache leeren und neu bauen.

Beispiele für Amplify-Einstellungen

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   # optional für speicherintensive Builds

4) Verwende eine Stabile amplify.yml für Builds

Gib Amplify eine reproduzierbare Build-Pipeline. Hier ist eine produktionsfreundliche Basiskonfiguration für 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

Häufige Fallstricke

• Wenn du den Lockfile-Manager oder Node-Versionen wechselst, leere den Cache in der Amplify-Konsole.
• Wenn deine App eine bestimmte Node-Version benötigt, füge eine .nvmrc im Repo-Root mit 18 oder 20 hinzu.

5) Behebe CORS (Wenn Du eine Externe API Aufrufst)

Wenn deine App mit einem Backend kommuniziert (z.B. Node, Rails, Laravel), füge deine Amplify-Domain und eigene Domain zur CORS-Allowlist des Backends hinzu.

Beispiel CORS-Regeln (konzeptionell):

• 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: nur wenn du Auth-Cookies benötigst

Warum es bricht: Lokal ist dein Origin http://localhost:3000. In Produktion ist es die Amplify-Domain oder deine eigene Domain. Wenn dein Backend diesen Origin nicht erkennt, lehnt es Anfragen ab — manchmal sichtbar als 500 in deiner App.

6) Konfiguriere Bildoptimierung

Next.js blockiert externe Bilder von nicht vertrauenswürdigen Domains. Auf Amplify können deine Bild-URLs von lokalen abweichen (z.B. CDN-Links). Füge sie zu images.domains oder remotePatterns hinzu.

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

Symptome von Fehlkonfiguration: Bilder scheitern stillschweigend, Hydrations-Mismatches oder Serverfehler wenn ein Bildlader während SSR fehlschlägt.

7) Leere Amplify Cache und Deploye Sauber Neu

Amplify cachet Abhängigkeiten und .next/cache. Wenn du env vars, next.config.mjs oder Lockfile-Details änderst, immer:

1. Amplify Console → Build settings → Clear cache
2. Ein Redeploy auslösen

Das erzwingt eine saubere Installation und vermeidet veraltete Artefakte, die Runtime-Crashes verursachen können.

8) Überprüfe Node Runtime und Speicher

• Füge .nvmrc mit einer unterstützten Version hinzu (z.B. 18).
• Wenn Builds speicherintensiv sind, setze NODE_OPTIONS=--max-old-space-size=4096 in Amplify env vars.
• Halte Abhängigkeiten schlank und prüfe auf native Module, die spezielle Runtime-Behandlung erfordern.

9) SSR vs. Statisch: Wisse Was Du Deployest

• SSG/ISR Seiten funktionieren generell gut mit Amplify's statischem Hosting + Next Server.
• SSR-Routen erfordern, dass der Standalone-Server reibungslos läuft.
• Wenn du Edge Functions oder erweiterte Middleware hast, bestätige die Kompatibilität mit Amplify's Runtime.

Schritt für Schritt: Von 500 zu 200 OK

A. Minimale Funktionierende 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. Produktions-Build-Befehle

pnpm install --frozen-lockfile
pnpm run build

Dann in Amplify setzen:

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

C. CORS Allowlist (Backend)

• Füge sowohl die Amplify Preview-Domain als auch deine eigene Domain hinzu.
• Deploye Backend-Änderungen neu und leere Config-Caches wenn dein Framework Configs cachet.

D. Invalidiere Amplify Cache

• Amplify Console → Clear cache
• Redeploy → Teste die Live-URL

Tiefgehende Fehlerbehebung (Wenn Es Immer Noch 500 Ist)

1) Prüfe Server Runtime Logs

• Öffne Amplify Build Logs und App Logs.

• Suche nach Fehlern wie:

  • ReferenceError: window is not defined (SSR-Code greift auf Browser-APIs zu)
  • TypeError: fetch failed (Backend nicht erreichbar oder CORS blockiert)
  • ENOENT: no such file or directory (Pfade die lokal existieren aber nicht im Build Output)

Fix: Schütze Browser-only Code mit typeof window !== 'undefined' oder verwende Dynamic Imports mit ssr: false.

2) Hydrations-Mismatch Verursacht Serverfehler

• Bedingte Darstellung oder Locales können während SSR Crashes verursachen.
• Überprüfe, dass alle in getServerSideProps abgerufenen Daten mit aktuellen env vars erreichbar sind.

Fix: Logge die Existenz von process.env Schlüsseln (nicht Werte) in Dev; stelle sicher, dass alle benötigten Vars in Amplify gesetzt sind.

3) API URLs Sind Relativ in SSR

• Relative Pfade die im Browser funktionieren, können auf dem Server scheitern.

Fix: Verwende absolute URLs aus env:

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

4) Bild-Domains Nicht Gewhitelistet

• 500er können durch Fehler in der Bildoptimierung entstehen.

Fix: Füge alle externen Hosts zu images.domains oder remotePatterns hinzu.

5) Node Version Mismatch

• Wenn lokal Node 20 läuft aber Amplify standardmäßig Node 18 nutzt, können native Pakete sich fehlverhalten.

Fix: Füge .nvmrc mit der Version hinzu, auf der du entwickelst, und gleiche dein lokales Node an.

6) ISR/Cache Invalidierung

• Wenn du ISR mit revalidate nutzt, stelle sicher, dass Revalidierungs-Tokens und Routen korrekt eingerichtet sind.
• Veraltete Renders können Fehlkonfigurationen verbergen, bis ein Pfad revalidiert wird und einen Server-Fetch auslöst, der fehlschlägt.

Fix: Bestätige fetch Endpoints, Auth Headers und Umgebungstokens in Amplify.

7) Middleware oder Edge Cases

• Entferne oder vereinfache middleware.ts temporär, um Runtime-Fehler zu isolieren.
• Wenn du auf erweiterte Headers/Cookies angewiesen bist, überprüfe, dass Amplify sie wie erwartet weiterleitet.

Zusammenfassung / Schnelle Erkenntnisse

• Setze output: "standalone" in next.config.mjs für Amplify SSR.
• Spiegle .env.local in Amplify Environment variables; prefixe Browser-Variablen mit NEXT_PUBLIC_.
• Whiteliste dein Amplify und eigenes Domain in Backend CORS.
• Füge alle CDN/API Hosts zur Next.js Image Config hinzu.
• Halte Node-Versionen mit .nvmrc gleich und deklariere die PNPM-Version.
• Leere Amplify Cache nach Env- oder Build-Config-Änderungen.
• Verwende absolute URLs in SSR (API_URL), keine relativen Pfade.
• Schütze Browser-only Code während SSR um Runtime-Crashes zu vermeiden.
• Prüfe Amplify Logs auf Stack Traces; behebe den exakten Fehlerpunkt.
• Deploye neu aus einem sauberen Zustand sobald Fixes eingespielt sind.

Handlungsaufruf (CTA)

Willst du deine Next.js App reibungslos auf AWS Amplify deployen — ohne 500-Fehler, CORS-Probleme oder kaputte Builds? Wenn du lieber einen Experten das Setup übernehmen lässt, beauftrage mich auf Fiverr, um dein Amplify-Deployment für produktionsreife Performance zu konfigurieren, debuggen und optimieren.

👉 Professionelle Next.js + AWS Amplify Setup-Unterstützung auf Fiverr

Optional: FAQ

F1: Mein Amplify Build ist erfolgreich, aber die Live-Seite zeigt 500. Warum? Die Runtime kann deine App nicht wie gebaut ausführen — meist wegen fehlendem output: "standalone", fehlenden env vars zur Laufzeit, CORS-Ablehnung oder Bild-Host-Beschränkungen.

F2: Muss ich Umgebungsvariablen prefixen? Ja, nur Variablen die im Browser verwendet werden, müssen geprefixed werden mit NEXT_PUBLIC_. Server-only Variablen sollten nicht geprefixed werden.

F3: Wie erlaube ich Bilder von meinem CDN? Füge den Host zu images.domains oder remotePatterns in next.config.mjs hinzu. Ohne das kann die Bildoptimierung fehlschlagen und Runtime-Probleme verursachen.

F4: Welche Node-Version sollte ich verwenden? Verwende eine stabile, unterstützte Version (Node 18 oder 20). Füge eine .nvmrc Datei hinzu, damit Amplify dieselbe Version wie die lokale Entwicklung verwendet.

F5: Ich habe env und CORS gefixt, bekomme aber immer noch 500. Was nun? Leere den Amplify Cache, deploye neu und inspiziere Logs. Überprüfe absolute API URLs in SSR, schütze Browser-only Code und prüfe auf Middleware/Edge Function Inkompatibilitäten.

F6: Kann ich 500er bei zukünftigen Deploys vermeiden? Ja — halte dich an das Spielbuch: Standalone Output, synchronisierte env vars, CORS Allowlist, Bild-Hosts, Node-Angleichung und Cache-Leerung bei Config-Änderungen.