Website-Build bricht ab: „JavaScript heap out of memory“
Kurz gesagt: Bricht der Build Ihrer Website oder Web-App mit „JavaScript heap out of memory“ ab, hat Node.js die Speichergrenze für seinen Heap erreicht. Das passiert besonders auf kleinen Servern, auf denen gleichzeitig Datenbank und Webserver laufen. Laut Node.js-Dokumentation (abgerufen November 2026) lässt sich die Grenze mit der Option „--max-old-space-size“ setzen, auf einem Rechner mit 2 GiB Arbeitsspeicher etwa auf 1536 MiB. Die nachhaltigere Lösung ist aber oft, gar nicht auf dem Produktivserver zu bauen, sondern anderswo, und nur das fertige Ergebnis hochzuladen.
Wie der Fehler aussieht
Typisch ist eine Ausgabe, die mit „FATAL ERROR“ beginnt und Begriffe wie „Reached heap limit“ und „Allocation failed – JavaScript heap out of memory“ enthält. Davor stehen oft lange Zeilen über die Speicherbereinigung, die Node.js vergeblich versucht hat. Der Prozess endet, und die Website bleibt auf dem alten Stand oder ist im schlimmsten Fall halb aktualisiert.
Betroffen sind vor allem Projekte, deren Oberfläche mit modernen Werkzeugen gebaut wird: ein Shop-Frontend mit einem JavaScript-Framework, eine Website mit einem statischen Seitengenerator, eine Web-App mit vielen Abhängigkeiten. Der Build bündelt Code, optimiert Bilder, erzeugt Seiten und Quellzuordnungen. Mit jeder neuen Funktion und jeder neuen Abhängigkeit braucht er mehr Speicher.
Ein Beispiel zur Veranschaulichung: Ein Reisebüro in Hannover betreibt seine Website mit einem Seitengenerator auf einem kleinen virtuellen Server. Mit jeder neuen Reise kommt eine Seite dazu. Eines Tages bricht das automatische Update nach dem Einpflegen neuer Angebote ab, obwohl am Code nichts geändert wurde.
Was hinter der Grenze steckt
Node.js führt JavaScript mit der Engine V8 aus. V8 verwaltet den Speicher in mehreren Bereichen. Für langlebige Daten gibt es die „old space“ genannte Generation. Laut Node.js-Dokumentation legt die Option --max-old-space-size die Höchstgröße dieses Bereichs in MiB fest. Nähert sich der Verbrauch der Grenze, verbringt V8 laut Dokumentation mehr Zeit mit der Speicherbereinigung. Reicht auch das nicht, bricht der Prozess mit dem bekannten Fehler ab.
Die Dokumentation gibt ein konkretes Beispiel: Auf einem Rechner mit 2 GiB Arbeitsspeicher könne man den Wert auf 1536 setzen, um etwas Speicher für anderes übrig zu lassen und Auslagerung zu vermeiden. Das zeigt den Kern des Problems: Die Grenze darf nicht höher sein als das, was der Server tatsächlich frei hat.
Erste Hilfe: die Grenze bewusst setzen
Die Option lässt sich direkt beim Aufruf angeben oder über die Umgebungsvariable NODE_OPTIONS. Laut Dokumentation ist NODE_OPTIONS eine durch Leerzeichen getrennte Liste von Optionen, die vor den Befehlszeilenoptionen gelesen werden. So erreicht man auch Werkzeuge, die Node.js intern starten:
NODE_OPTIONS="--max-old-space-size=1536" npm run build
Bevor Sie einen Wert eintragen, prüfen Sie, wie viel Arbeitsspeicher der Server hat und wie viel davon Datenbank, Webserver und andere Dienste im laufenden Betrieb brauchen. Ein zu hoher Wert führt nicht zu einem schnelleren Build, sondern dazu, dass das System Speicher auslagert oder andere Prozesse beendet. Im schlimmsten Fall geht während des Builds die Website selbst in die Knie.
Die bessere Lösung: woanders bauen
Für die meisten Betriebe ist es sinnvoller, den Build vom Produktivserver zu trennen:
| Variante | Vorteil | Worauf achten |
|---|---|---|
| Build in einer CI-Pipeline | Eigene, frische Umgebung mit genug Speicher | Zugangsdaten für das Hochladen sicher hinterlegen |
| Build auf dem Rechner der Entwicklerin | Kein zusätzlicher Dienst nötig | Gleiche Node-Version wie geplant verwenden |
| Build auf einem separaten Server | Volle Kontrolle | Wartung eines weiteren Systems |
In allen Fällen lädt man danach nur das fertige Ergebnis auf den Server. Der Produktivserver muss dann nur noch ausliefern, nicht mehr bauen. Das hat einen Nebeneffekt: Ein abgebrochener Build hinterlässt keine halbfertige Website, weil das alte Ergebnis so lange online bleibt, bis das neue vollständig hochgeladen ist.
Den Speicherbedarf des Builds senken
Unabhängig davon, wo Sie bauen, lohnt ein Blick auf die größten Speicherfresser. Fragen Sie Ihren Entwickler nach diesen Punkten:
- Quellzuordnungen (Source Maps): Werden sie für die Produktivversion gebraucht? Sie kosten beim Build viel Speicher.
- Bildoptimierung im Build: Viele Generatoren verkleinern Bilder bei jedem Build neu. Ein Zwischenspeicher für bereits optimierte Bilder oder eine Optimierung beim Hochladen entlastet.
- Große Datenquellen: Werden alle Produkte oder Seiten auf einmal in den Speicher geladen? Bei großen Katalogen hilft schrittweises Verarbeiten.
- Veraltete Abhängigkeiten: Neuere Versionen von Build-Werkzeugen gehen teils sparsamer mit Speicher um. Das ist kein Automatismus, aber ein Prüfpunkt.
Hinweise zur Fehlersuche
Wenn Sie wissen wollen, was genau den Speicher füllt, bietet Node.js Werkzeuge an. Die Dokumentation listet etwa eine Option, die kurz vor Erreichen der Grenze einen Speicherabzug („Heap Snapshot“) schreibt. Damit kann Ihr Entwickler sehen, welche Daten den Speicher belegen. Für den Alltag reicht oft schon die Beobachtung, ob der Speicherbedarf mit der Zahl der Seiten oder Produkte wächst.
Was Sie nach der Umstellung festhalten sollten
Damit der Fehler nicht beim nächsten Personalwechsel wieder auftaucht, gehört der Build-Ablauf in Ihre Website-Dokumentation. Notieren Sie, mit welcher Node-Version gebaut wird, wo der Build läuft, welche Umgebungsvariablen gesetzt sind und wie das Ergebnis auf den Server kommt. Halten Sie außerdem fest, wer benachrichtigt wird, wenn ein Build scheitert, und wie man im Notfall auf die vorherige Version zurückwechselt. Diese wenigen Zeilen sparen viel Zeit, wenn eine neue Agentur oder ein neuer Entwickler übernimmt. Eine automatische Meldung bei fehlgeschlagenem Build per Mail oder Team-Chat sorgt zusätzlich dafür, dass niemand erst durch Kundenhinweise merkt, dass neue Inhalte nicht online gegangen sind.
Häufige Fragen
Reicht es, einfach mehr Arbeitsspeicher beim Hoster zu buchen?
Kurzfristig oft ja. Wächst die Website weiter, stehen Sie aber bald wieder vor demselben Problem. Wer den Build vom Server trennt, löst es dauerhaft.
Warum lief der Build gestern noch?
Weil der Speicherbedarf schleichend wächst. Neue Seiten, neue Bilder oder ein Update einer Abhängigkeit können den Ausschlag geben, ohne dass am eigenen Code etwas geändert wurde.
Ist die Website während des Fehlers offline?
Das hängt davon ab, wie der Build eingerichtet ist. Wird direkt in den Ordner gebaut, den der Webserver ausliefert, kann ein Abbruch eine halbfertige Version hinterlassen. Bauen Sie deshalb in einen separaten Ordner und wechseln Sie erst nach erfolgreichem Build.
Welchen Wert soll ich für --max-old-space-size nehmen?
Einen, der unter dem tatsächlich freien Speicher liegt. Das Beispiel der Node.js-Dokumentation mit 1536 MiB bei 2 GiB Gesamtspeicher zeigt die Richtung, ist aber kein fester Wert für jeden Server.
Wenn Ihr Website-Build auf dem Server regelmäßig am Speicher scheitert, richten wir mit Ihnen gern einen Ablauf ein, bei dem woanders gebaut wird: Projekt anfragen.