Corriger « Failed to find Server Action » après un déploiement Next.js.

Quand un composant client appelle une Server Action, le navigateur envoie un POST avec un en-tête Next-Action qui contient l’identifiant de l’action. Le serveur cherche cet identifiant dans la compilation qu’il exécute. S’il ne le trouve pas, il journalise Error: Failed to find Server Action "7f3a…". This request might be from an older or newer deployment. et répond par un 404. Dans la console du navigateur, le même échec se lit Server Action "7f3a…" was not found on the server.

Next.js rend ces identifiants non déterministes à dessein, pour la sécurité, et ils peuvent changer d’une compilation à l’autre. L’erreur veut donc presque toujours dire que la page dans le navigateur et le serveur qui lui répond viennent de compilations différentes.

Un second message, Server Reference ID did not match the expected format, est autre chose : l’identifiant n’a même pas la forme de ceux que produit cette version de Next.js. La documentation de Next.js donne deux causes : un client et un serveur sur des versions de Next.js aux formats différents, ou des requêtes malformées, comme celles des scanneurs de sécurité. S’il arrive en rafale depuis une seule adresse IP, c’est sans doute un scanneur, et vous pouvez l’ignorer.

Parcourez le tableau de haut en bas. La première ligne est celle que presque tout le monde rencontre, parce qu’elle se produit à chaque déploiement, chez n’importe quel hébergeur.

Quelqu’un ouvre votre formulaire à 10 h. Vous déployez à 10 h 05. À 10 h 07, il clique sur Enregistrer. Son onglet exécute encore le JavaScript de 10 h, qui envoie l’identifiant d’action de 10 h à un serveur qui exécute la compilation de 10 h 05. C’est tout le bogue, et aucun hébergeur ne peut le faire disparaître complètement à moins de garder l’ancienne compilation en marche à côté de la nouvelle.

Next.js a un réglage pour ça. Avec `deploymentId`, les navigations côté client envoient un en-tête x-deployment-id, le serveur répond avec le sien et, s’ils diffèrent, le client recharge la page au complet au lieu de naviguer côté client. L’utilisateur arrive sur la nouvelle compilation et ses nouveaux identifiants. Toute valeur qui change à chaque déploiement fait l’affaire :

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Any value that changes on every deploy. Canner sets CANNER_DEPLOYMENT_ID
  // during each build; elsewhere use your git SHA or CI build number.
  deploymentId: process.env.CANNER_DEPLOYMENT_ID,
};

export default nextConfig;

L’identifiant de déploiement agit à la navigation suivante. Un utilisateur qui reste sur une page et clique sur un bouton peut encore envoyer un appel périmé. Quand l’action est introuvable, la promesse attendue par le client est rejetée avec une erreur que reconnaît unstable_isUnrecognizedActionError, de next/navigation (dans Next.js 16.2; le préfixe unstable_ veut dire que la fonction peut changer). Gérez ce cas au lieu de laisser un bouton mort :

"use client";
import { unstable_isUnrecognizedActionError } from "next/navigation";
import { saveDraft } from "./actions";

export function SaveButton({ id }: { id: string }) {
  async function onClick() {
    try {
      await saveDraft(id);
    } catch (err) {
      // This tab was loaded before the last deploy.
      if (unstable_isUnrecognizedActionError(err)) {
        if (confirm("This page was updated. Reload to continue?")) location.reload();
        return;
      }
      throw err;
    }
  }
  return <button onClick={onClick}>Save</button>;
}

Next.js chiffre les variables qu’une Server Action capture avant de les envoyer au navigateur. Par défaut, chaque compilation crée sa propre clé. Quand plusieurs instances servent le même site, une action chiffrée par l’une ne peut pas être déchiffrée par une autre, et Next.js le signale comme « Failed to find Server Action ».

La correction du guide d’auto-hébergement est une clé commune : en base64, de 16, 24 ou 32 octets. Elle est lue à la compilation et intégrée à la sortie : la définir seulement sur le serveur en marche ne sert à rien.

• Sur Canner, ajoutez-la sous l’onglet Variables d’environnement du projet avec la portée production ou toutes, et marquez-la sensible. Une variable à portée exécution seulement n’atteint jamais la compilation : la clé ne serait pas intégrée. Voir les portées.
• Une clé commune ne rend pas les identifiants d’action stables entre deux compilations différentes. Elle règle le déchiffrement entre instances, pas les onglets périmés.

# Generate once, keep it in your secrets store
openssl rand -base64 32

# It must be present when `next build` runs
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=<the 44-character value> next build

Canner exécute chaque projet comme un seul processus next start de longue durée (déroulement d’un déploiement). Un déploiement de production compile la nouvelle version, exécute votre commande de mise en production s’il y en a une, puis démarre la nouvelle compilation à la place de l’ancienne. Elle prend le trafic dès qu’elle répond à la vérification d’état. Deux compilations ne répondent jamais en même temps en production : les causes liées à plusieurs instances ne peuvent donc pas se produire.

Les onglets périmés, si. Canner ne garde pas l’ancienne compilation en marche pour les vieux onglets, comme le fait la Skew Protection de Vercel : définissez deploymentId et gérez l’appel rejeté comme ci-dessus. Chaque aperçu de demande de tirage est une compilation distincte, à sa propre adresse, et ne se mélange pas à la production.

Deux autres choses changent la compilation sous les pieds de vos utilisateurs : le retour arrière automatique recompile votre dernier bon commit, et un retour arrière manuel en recompile un plus ancien. Ce sont de nouvelles compilations avec de nouveaux identifiants d’action : traitez-les comme n’importe quel déploiement.