Comment Résoudre l'Erreur "500 Internal Server Error" lors du Déploiement d'une App Next.js sur AWS Amplify

Introduction

Vous avez envoyé une belle app Next.js vers AWS Amplify. Le build a réussi, les logs semblaient propres, votre domaine pointait correctement… et puis : "500 Internal Server Error." Aïe.

Si votre app fonctionne parfaitement sur localhost mais plante dans le runtime d'Amplify, vous n'êtes pas seul. Le coupable n'est presque jamais la logique de votre app — c'est la configuration runtime : output SSR, variables d'environnement, CORS, optimisation des images, versions Node ou cache Amplify.

Dans ce guide, vous apprendrez un processus fiable et de qualité production pour diagnostiquer et corriger les erreurs 500 sur AWS Amplify pour Next.js. Nous passerons en revue les fichiers exacts à ajuster, ce qu'Amplify attend pour le SSR, comment exposer correctement les variables d'environnement et comment garder images, APIs et cache synchronisés — pour que votre déploiement se comporte comme votre environnement local.

À la fin, vous aurez une checklist reproductible pour déployer des apps Next.js sur Amplify sans mystérieux 500 — plus des recettes de dépannage pour les cas particuliers qui font dérailler la plupart des équipes.

Qu'est-ce Qui Cause un 500 sur Amplify pour Next.js ?

Un 500 signifie que le serveur a planté ou a lancé une erreur au runtime. Sur Amplify, cela arrive généralement parce que :

• Désajustement de l'output SSR — Next.js a besoin de output: "standalone" pour qu'Amplify sache comment exécuter le serveur.
• Variables ENV non disponibles au runtime — elles étaient présentes localement mais non injectées dans Amplify ou non préfixées pour le navigateur.
• CORS ou désajustement d'API — votre backend rejette les requêtes du domaine Amplify.
• Optimisation d'images non configurée — les hôtes d'images distants ne sont pas autorisés dans next.config.
• Mauvaise version Node ou cache — cache obsolète ou runtime Node incompatible casse le serveur.

La solution ? Aligner build + runtime pour correspondre au dev local, puis vider les caches et redéployer.

Le Plan d'Action : Corriger les Erreurs 500 de Next.js sur AWS Amplify

1) Confirmez que le Local est Sain (D'abord la Ligne de Base)

Avant d'ajuster Amplify, prouvez que l'app est solide localement :

rm -rf .next
pnpm install
pnpm dev

Puis testez un build de type production localement :

pnpm build
pnpm start

Si cela passe et affiche des pages, vous avez confirmé que le problème est la configuration de déploiement, pas votre code.

Vérification ENV Locale

Créez ou vérifiez .env.local :

NEXT_PUBLIC_SITE_URL=http://localhost:3000
API_URL=https://api.yourdomain.com
NEXT_PUBLIC_IMG_CDN=https://cdn.yourdomain.com
# Ajoutez les tokens/clés dont votre app a besoin au runtime

• Secrets serveur uniquement : pas de préfixe NEXT_PUBLIC_.
• Valeurs visibles côté client : doivent commencer par NEXT_PUBLIC_.

2) Forcer le Output Standalone pour SSR

Amplify attend un bundle serveur Next.js standalone. Dans next.config.mjs :

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  output: "standalone", // ✅ crucial pour Amplify SSR
  images: {
    domains: [
      "yourdomain.com",
      "cdn.yourdomain.com",
      "lh3.googleusercontent.com",
      "gravitar.com",
      "images.unsplash.com",
      "*.amplifyapp.com".replace("*.", "") // wildcard non supporté, ajoutez votre hôte si nécessaire
    ],
    remotePatterns: [
      { protocol: "https", hostname: "cdn.yourdomain.com", pathname: "/**" },
      { protocol: "https", hostname: "yourdomain.com", pathname: "/**" },
      // ajoutez plus si nécessaire
    ],
  },
  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: {
    // uniquement si vous utilisez des fonctionnalités spécifiques ; sinon omettez
  }
};

export default nextConfig;

Pourquoi c'est important : Sans output: "standalone", Amplify peut construire avec succès mais échouer à exécuter le bundle serveur au runtime — causant un 500.

Astuce pro : Si vous faites un whitelist dynamique des hôtes d'images, assurez-vous qu'ils sont présents dans les variables d'environnement Amplify (plus à ce sujet ci-dessous).

3) Rendre les Variables d'Environnement Disponibles dans Amplify

Votre runtime Next.js sur Amplify n'hérite pas magiquement de .env.local. Vous devez configurer les env vars dans la Amplify Console → Environment variables ou via votre CI.

Règles pratiques

• Tout ce qui est utilisé par le navigateur doit avoir le préfixe NEXT_PUBLIC_.
• Tout ce qui est utilisé uniquement par le serveur reste sans préfixe.
• Variables d'environnement modifiées ? Videz le cache Amplify et reconstruisez.

Exemples à configurer dans 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   # optionnel pour les builds gourmands en mémoire

4) Utiliser un amplify.yml Stable pour les Builds

Fournissez à Amplify un pipeline de build reproductible. Voici une configuration de base production-friendly pour 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

Pièges courants

• Si vous changez de gestionnaire de lockfile ou de versions Node, videz le cache dans la console Amplify.
• Si votre app nécessite une version Node spécifique, ajoutez un .nvmrc à la racine du repo avec 18 ou 20.

5) Corriger CORS (Si Vous Appelez une API Externe)

Si votre app communique avec un backend (ex. Node, Rails, Laravel), ajoutez votre domaine Amplify et domaine personnalisé à l'allowlist CORS du backend.

Exemple de règles CORS (conceptuel) :

• 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 : uniquement si vous avez besoin de cookies d'authentification

Pourquoi ça casse : Localement, votre origin est http://localhost:3000. En production, c'est le domaine Amplify ou votre domaine personnalisé. Si votre backend ne reconnaît pas cette origin, il rejette les requêtes — parfois visible comme un 500 dans votre app.

6) Configurer l'Optimisation des Images

Next.js bloque les images externes de domaines non fiables. Sur Amplify, vos URLs d'images peuvent différer du local (ex. liens CDN). Ajoutez-les à images.domains ou remotePatterns.

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

Symptômes de mauvaise configuration : afbeeldingen die stilzwijgend falen, hydratatie-mismatches, of serverfouten als een beeldlader faalt tijdens SSR.

7) Vider le Cache Amplify et Redéployer Proprement

Amplify met en cache les dépendances et .next/cache. Quand vous changez les env vars, next.config.mjs ou les détails du lockfile, toujours :

1. Amplify Console → Build settings → Clear cache
2. Déclenchez un Redeploy

Cela force une installation propre et évite les artéfacts obsolètes qui peuvent causer des crashes runtime.

8) Vérifier le Runtime Node et la Mémoire

• Ajoutez .nvmrc avec une version supportée (ex. 18).
• Si les builds sont lourds, configurez NODE_OPTIONS=--max-old-space-size=4096 dans les env vars Amplify.
• Gardez les dépendances légères et vérifiez les modules natifs qui nécessitent un traitement runtime spécial.

9) SSR vs. Statique : Sachez Ce Que Vous Déployez

• Les pages SSG/ISR fonctionnent généralement bien avec l'hébergement statique d'Amplify + serveur Next.
• Les routes SSR nécessitent que le serveur standalone fonctionne sans problème.
• Si vous avez des edge functions ou du middleware avancé, confirmez la compatibilité avec le runtime d'Amplify.

Étape par Étape : De 500 à 200 OK

A. next.config.mjs Minimum Fonctionnel

/** @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. Commandes de Build de Production

pnpm install --frozen-lockfile
pnpm run build

Puis configurez dans Amplify :

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

C. Allowlist CORS (Backend)

• Ajoutez à la fois le domaine preview Amplify et votre domaine personnalisé.
• Redéployez les modifications backend et videz les caches de config si votre framework met en cache les configs.

D. Invalider le Cache Amplify

• Amplify Console → Clear cache
• Redeploy → Testez l'URL en direct

Dépannage Approfondi (Quand C'est Toujours 500)

1) Vérifier les Logs Runtime du Serveur

• Ouvrez les build logs et app logs d'Amplify.

• Cherchez des erreurs comme :

  • ReferenceError: window is not defined (code SSR accédant aux APIs navigateur)
  • TypeError: fetch failed (backend non accessible ou CORS bloqué)
  • ENOENT: no such file or directory (chemins qui existent localement mais pas dans le build output)

Correction : Protégez le code navigateur-only avec typeof window !== 'undefined' ou utilisez des dynamic imports avec ssr: false.

2) Désajustement d'Hydratation Cause Erreur Serveur

• Le rendu conditionnel ou les locales peuvent causer des crashes pendant le SSR.
• Vérifiez que toutes les données récupérées dans getServerSideProps sont accessibles avec les env vars actuelles.

Correction : Loggez l'existence des clés process.env (pas les valeurs) en dev ; assurez-vous que toutes les vars nécessaires sont configurées dans Amplify.

3) Les URLs d'API Sont Relatives en SSR

• Les chemins relatifs qui fonctionnent dans le navigateur peuvent échouer sur le serveur.

Correction : Utilisez des URLs absolues provenant de env :

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

4) Domaines d'Images Non en Whitelist

• Les 500 peuvent provenir de défaillances de l'optimisation d'images.

Correction : Ajoutez tous les hôtes externes à images.domains ou remotePatterns.

5) Désajustement de Version Node

• Si localement Node 20 tourne mais qu'Amplify utilise Node 18 par défaut, les paquets natifs peuvent mal se comporter.

Correction : Ajoutez .nvmrc avec la version sur laquelle vous développez et alignez votre Node local.

6) Invalidation ISR/Cache

• Si vous utilisez ISR avec revalidate, assurez-vous que les tokens de revalidation et les routes sont correctement configurés.
• Les rendus obsolètes peuvent masquer une mauvaise configuration jusqu'à ce qu'un chemin soit revalidé et déclenche un fetch serveur qui échoue.

Correction : Confirmez les endpoints fetch, les headers d'auth et les tokens d'environnement dans Amplify.

7) Middleware ou Cas Particuliers

• Supprimez ou simplifiez middleware.ts temporairement pour isoler les échecs runtime.
• Si vous dépendez de headers/cookies avancés, vérifiez qu'Amplify les transmet comme prévu.

Points Clés / Résumé Rapide

• Configurez output: "standalone" dans next.config.mjs pour Amplify SSR.
• Reflétez .env.local dans Amplify Environment variables ; préfixez les variables navigateur avec NEXT_PUBLIC_.
• Ajoutez votre Amplify et domaine personnalisé au whitelist CORS backend.
• Ajoutez tous les hôtes CDN/API à la config Next.js image.
• Gardez les versions Node alignées avec .nvmrc et déclarez la version PNPM.
• Videz le cache Amplify après les modifications env ou config de build.
• Utilisez des URLs absolues en SSR (API_URL), pas de chemins relatifs.
• Protégez le code navigateur-only pendant le SSR pour éviter les crashes runtime.
• Vérifiez les logs Amplify pour les stack traces ; corrigez le point exact de défaillance.
• Redéployez depuis un état propre une fois les corrections appliquées.

Appel à l'Action (CTA)

Vous voulez déployer votre app Next.js sans problème sur AWS Amplify — sans erreurs 500, problèmes CORS ou builds cassés ? Si vous préférez qu'un expert gère la configuration pour vous, engagez-moi sur Fiverr pour configurer, déboguer et optimiser votre déploiement Amplify pour des performances prêtes pour la production.

👉 Obtenez un support professionnel de configuration Next.js + AWS Amplify sur Fiverr

Optionnel : FAQ

Q1 : Mon build Amplify réussit mais le site en direct affiche 500. Pourquoi ? Le runtime ne peut pas exécuter votre app telle que construite — généralement à cause d'un output: "standalone" manquant, de vars env manquantes au runtime, d'un rejet CORS ou de restrictions d'hôtes d'images.

Q2 : Dois-je préfixer les variables d'environnement ? Oui, seules les variables utilisées dans le navigateur doivent être préfixées avec NEXT_PUBLIC_. Les variables serveur-only ne doivent pas être préfixées.

Q3 : Comment autoriser les images de mon CDN ? Ajoutez l'hôte à images.domains ou remotePatterns dans next.config.mjs. Sans cela, l'optimisation d'images peut échouer et causer des problèmes runtime.

Q4 : Quelle version de Node dois-je utiliser ? Utilisez une version stable et supportée (Node 18 ou 20). Ajoutez un fichier .nvmrc pour qu'Amplify utilise la même version que le développement local.

Q5 : J'ai corrigé env et CORS mais j'ai toujours 500. Que faire ? Videz le cache Amplify, redéployez et inspectez les logs. Vérifiez les URLs absolues d'API en SSR, protégez le code navigateur-only et vérifiez les incompatibilités middleware/edge functions.

Q6 : Puis-je éviter les 500 lors de futurs déploiements ? Oui — suivez le plan : standalone output, env vars synchronisées, allowlist CORS, hôtes d'images, alignement Node et vidage de cache lors de changements de config.