Vercel-Build schlägt nach dem Upgrade fehl: systematisch vorgehen

Das Upgrade lief lokal problemlos. npm run dev startet, die Seiten laden, alles sieht gut aus. Dann der Push, und Vercel meldet: „Build failed“. Oder schlimmer: Der Build läuft durch, aber die Preview-Deployment-Seite zeigt einen Fehler.

Build-Fehler nach Major-Upgrades haben selten eine einzige Ursache. Meist treffen mehrere Änderungen gleichzeitig ein: neue Framework-Version, neue Node.js-Mindestversion, Abhängigkeiten mit neuen Peer-Dependencies. Wer wahllos an Stellschrauben dreht, verliert schnell den Überblick. Besser ist ein festes Vorgehen.

1. Das Build-Log vollständig lesen

Öffnen Sie im Vercel-Dashboard das fehlgeschlagene Deployment und dort das Build-Log. Lesen Sie nicht nur die letzte Zeile. Die letzte Meldung lautet oft nur Command "npm run build" exited with 1, die eigentliche Ursache steht weiter oben.

Achten Sie auf drei Phasen:

• Installation (npm install, pnpm install, yarn install): Fehler wie ERESOLVE unable to resolve dependency tree oder ein veralteter Lockfile.
• Build (next build o. Ä.): Typfehler, Modul nicht gefunden, Konfigurationsfehler.
• Prerendering bzw. Seitengenerierung: Fehler beim Erzeugen statischer Seiten, meist mit dem Pfad der betroffenen Route.

Die Phase sagt Ihnen, wo Sie suchen müssen.

2. Lokal exakt nachstellen

npm run dev ist kein Build. Der Entwicklungsserver ist toleranter, kompiliert Seiten erst bei Bedarf und prüft weder Typen noch Prerendering. Stellen Sie den Build lokal so nach, wie Vercel ihn ausführt:

rm -rf node_modules .next
npm ci
npm run build

npm ci installiert exakt aus dem Lockfile und schlägt fehl, wenn package.json und Lockfile nicht zusammenpassen, genau wie in einer sauberen Build-Umgebung. Bei pnpm entspricht das pnpm install --frozen-lockfile.

Noch näher an Vercel kommen Sie mit der Vercel CLI, die Projekt-Einstellungen und Umgebungsvariablen übernimmt:

npx vercel pull --environment=preview
npx vercel build

Läuft der Build lokal durch, auf Vercel aber nicht, liegt die Ursache in der Umgebung, nicht im Code. Dann geht es mit Schritt 4 weiter.

3. Typische Ursachen im Code

Geänderte APIs des Frameworks

Major-Versionen entfernen, was vorher als veraltet markiert war. Bei Next.js betrifft das in jüngeren Versionen zum Beispiel:

• params, searchParams, cookies() und headers() sind asynchron. Seit Next.js 16 gibt es den synchronen Zugriff aus der Übergangszeit nicht mehr.
• Die Middleware-Datei heißt jetzt proxy.ts; middleware.ts ist veraltet.
• next build verwendet standardmäßig Turbopack. Enthält die next.config eine eigene webpack-Konfiguration, bricht der Build ab, auch wenn die Konfiguration von einem Plugin stammt.
• next lint wurde entfernt, und next build führt keine Lint-Prüfung mehr aus.

// vorher
export default function Seite({ params }: { params: { slug: string } }) {
  return <h1>{params.slug}</h1>;
}

// nachher
export default async function Seite({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}

Lesen Sie den offiziellen Upgrade-Guide der Zielversion von oben bis unten, bevor Sie Fehler einzeln beheben. Viele Projekte bieten Codemods an, die mechanische Änderungen automatisch erledigen. Prüfen Sie deren Ergebnis trotzdem im Diff.

Abhängigkeiten, die nicht mitgezogen sind

Eine UI-Bibliothek, ein CMS-SDK oder ein Auth-Paket unterstützt die neue React- oder Next.js-Version noch nicht. Das zeigt sich als Peer-Dependency-Konflikt bei der Installation oder als Laufzeitfehler beim Prerendering. Optionen in dieser Reihenfolge:

1. Prüfen, ob es eine kompatible Version des Pakets gibt.
2. Prüfen, ob das Paket noch gepflegt wird oder ersetzt werden sollte.
3. Nur als Übergang: Installation mit --legacy-peer-deps bzw. über overrides in der package.json. Das verschiebt das Problem, wenn das Paket tatsächlich inkompatibel ist.

Typfehler, die vorher keine waren

next build prüft TypeScript-Typen, der Entwicklungsserver nicht. Neue Versionen von Frameworks und Bibliotheken bringen oft strengere oder geänderte Typdefinitionen mit. Ein Aufruf, der jahrelang kompilierte, ist plötzlich ein Fehler. Führen Sie die Typprüfung lokal getrennt aus, das ist schneller als ein kompletter Build:

npx tsc --noEmit

Die Option typescript.ignoreBuildErrors in der next.config lässt den Build trotz Typfehlern durchlaufen. Sie ist verlockend, verschiebt die Fehler aber nur in die Laufzeit, wo sie Ihre Nutzer treffen. Als Dauerlösung ist sie ungeeignet.

Server- und Client-Code vermischt

Neue Bundler-Versionen sind strenger. Fehlermeldungen wie Module not found: Can't resolve 'fs' bedeuten, dass Client-Code ein Modul importiert, das Node.js-Funktionen nutzt. Die saubere Lösung ist, die Importkette zu trennen, statt das Modul im Bundler auszublenden.

4. Typische Ursachen in der Umgebung

Node.js-Version

Neue Framework-Versionen setzen oft eine höhere Node.js-Mindestversion voraus. Vercel verwendet die Version aus den Projekt-Einstellungen oder, falls angegeben, aus engines in der package.json. Legen Sie die Version explizit fest:

{
  "engines": {
    "node": "22.x"
  }
}

Prüfen Sie lokal mit node -v, dass Sie mit derselben Hauptversion bauen.

Groß- und Kleinschreibung in Importpfaden

macOS und Windows unterscheiden bei Dateinamen standardmäßig nicht zwischen Groß- und Kleinschreibung, die Linux-Umgebung von Vercel schon. import Header from "./header" funktioniert lokal, auch wenn die Datei Header.tsx heißt, und bricht auf Vercel ab. Ein Upgrade kann solche Fehler sichtbar machen, wenn Dateien umbenannt wurden.

Umgebungsvariablen

Variablen werden in Vercel pro Umgebung gepflegt: Production, Preview, Development. Eine Variable, die nur für Production gesetzt ist, fehlt im Preview-Build. Neue Versionen von SDKs prüfen ihre Konfiguration zudem oft schon beim Build und brechen ab, wo sie früher erst zur Laufzeit gescheitert sind. Vergleichen Sie die Liste mit Ihrer lokalen .env.

Build-Cache

Gelegentlich bringt ein alter Build-Cache Artefakte der vorherigen Version mit. Starten Sie das Deployment im Dashboard über „Redeploy“ neu und deaktivieren Sie dabei die Option, den vorhandenen Build-Cache zu verwenden. Alternativ erzwingt die Umgebungsvariable VERCEL_FORCE_NO_BUILD_CACHE=1 einen Build ohne Cache. Hilft das, war der Cache die Ursache. Hilft es nicht, haben Sie eine Variable ausgeschlossen.

5. Upgrade in kleinen Schritten

Ein Upgrade von mehreren Major-Versionen auf einmal ist schwer zu debuggen, weil sich die Ursachen überlagern. Leichter wird es so:

1. Eigenen Branch anlegen, nie direkt auf main.
2. Zuerst Node.js anheben und bauen.
3. Dann das Framework um eine Major-Version anheben, Codemods ausführen, bauen.
4. Dann abhängige Pakete aktualisieren, bauen.
5. Jeden funktionierenden Zwischenstand committen.
6. Das Preview-Deployment des Branches durchklicken, nicht nur den grünen Haken abwarten.

Erst wenn das Preview-Deployment fachlich geprüft ist, wird der Branch gemergt. So bleibt Ihre Produktion während des gesamten Upgrades unberührt.

Checkliste

• Build-Log vollständig gelesen, Phase identifiziert
• Build lokal mit npm ci && npm run build nachgestellt
• Upgrade-Guide der Zielversion gelesen, Codemods ausgeführt
• Peer-Dependencies und Kompatibilität der Pakete geprüft
• Node.js-Version lokal und auf Vercel identisch
• Importpfade auf Groß- und Kleinschreibung geprüft
• Umgebungsvariablen für Preview gesetzt
• Redeploy ohne Build-Cache getestet
• Preview-Deployment manuell geprüft

Häufige Fragen

Warum läuft der Build lokal, aber nicht auf Vercel?

Häufig, weil lokal kein echter Build lief: npm run dev kompiliert nur bei Bedarf und prüft weder Typen noch Prerendering. Läuft auch ein sauberer lokaler Build mit npm ci und npm run build durch, liegt die Ursache meist in der Umgebung. Typisch sind eine andere Node.js-Version, Groß- und Kleinschreibung in Importpfaden, fehlende Umgebungsvariablen für Preview oder ein alter Build-Cache.

Darf ich typescript.ignoreBuildErrors setzen, damit der Build durchläuft?

Als Dauerlösung nicht. Die Option lässt den Build trotz Typfehlern durchlaufen, verschiebt die Fehler aber in die Laufzeit, wo sie Ihre Nutzer treffen. Besser ist, die Typprüfung lokal mit npx tsc --noEmit auszuführen und die Fehler zu beheben.

Wie upgrade ich über mehrere Major-Versionen, ohne den Überblick zu verlieren?

In kleinen Schritten auf einem eigenen Branch: zuerst Node.js anheben, dann das Framework um eine Major-Version, dann die abhängigen Pakete, und nach jedem Schritt bauen. Jeden funktionierenden Zwischenstand committen Sie, damit sich Ursachen nicht überlagern. Gemergt wird erst, wenn das Preview-Deployment fachlich geprüft ist.

---

Ein Build-Fehler nach einem Major-Upgrade ist eine typische Aufgabe im Prozess-Abo. Sie legen ihn als Karte auf Ihr Board, hängen das Build-Log an und laden uns in Ihr Repository bei GitHub, GitLab, Bitbucket oder Azure DevOps ein. Wenn wir starten, stehen die Abnahmekriterien auf der Karte, etwa: Der Build läuft im Preview-Deployment durch, und die genannten Seiten funktionieren. 48 Stunden nach Start (gezählt Mo 8 – Fr 16 Uhr) erhalten Sie einen Pull Request auf einem eigenen Branch. Ein Senior-Entwickler hat ihn geprüft und freigegeben, und über den Merge entscheiden Sie. Ein Upgrade über mehrere Major-Versionen teilen wir in Schritte wie oben auf, jeden als eigene Karte mit eigenen Kriterien. Die erste Aufgabe erledigen wir kostenlos, eine pro Unternehmen. Mehr dazu unter Fehler beheben und im Leistungskatalog.