WordPress-Wartungsmodus: hängengebliebenen Modus beheben und gezielt nutzen

Nach einem Update zeigt die Website statt der Startseite nur noch den Satz „Diese Website ist aufgrund planmäßiger Wartungsarbeiten vorübergehend nicht verfügbar“, und auch der Login unter /wp-admin/ antwortet nicht mehr. Dahinter steckt fast immer eine einzige Datei: .maintenance im Hauptverzeichnis von WordPress. Diese Anleitung erklärt, wie der Wartungsmodus technisch funktioniert, wie Sie einen hängengebliebenen Modus sicher beenden und wie Sie ihn für eigene Arbeiten gezielt einschalten, ohne sich selbst auszusperren. Alle Befehle und Ausgaben stammen aus einem Test mit WordPress 7.1.2 und WP-CLI 2.12.0.

Voraussetzungen

• WordPress ab Version 4.6, getestet mit WordPress 7.1.2 auf PHP 8.4
• Zugriff auf das Dateisystem des Webspace: SFTP- oder FTP-Zugang, alternativ der Dateimanager im Kundenmenü des Hosters
• Für die Befehle auf der Kommandozeile: SSH-Zugang mit installiertem WP-CLI (getestet mit 2.12.0)
• Ein Konto mit der Rolle Administrator, um nach der Reparatur Updates erneut anzustoßen
• Ein aktuelles Backup von Dateien und Datenbank, bevor Sie Updates wiederholen oder Dateien ersetzen

Schritt 1: Verstehen, was der Wartungsmodus technisch ist

WordPress hat keinen Schalter für den Wartungsmodus in der Datenbank. Beim Laden jeder Seite ruft der Kern die Funktion wp_maintenance() auf. Sie prüft, ob im Installationsverzeichnis (dem Ordner mit wp-config.php und wp-load.php) eine Datei namens .maintenance liegt. Diese Datei enthält nur eine Zeile PHP mit einem Zeitstempel:

<?php $upgrading = 1790794331; ?>

Ist der Zeitstempel jünger als zehn Minuten, bricht WordPress die Anfrage ab und sendet eine Hinweisseite mit dem Status 503 und dem Header Retry-After: 600. Im Test antworteten in diesem Zustand nicht nur die Startseite, sondern auch /wp-admin/, /wp-login.php und die REST-API unter /wp-json/ mit 503. Sie kommen also auch als Administrator nicht mehr ins Backend.

Angelegt wird die Datei vom Updater: beim Core-Update, bei Theme-Updates und bei Plugin-Updates, sofern das Plugin aktiv ist und tatsächlich ein Update ansteht. Nach erfolgreichem Abschluss löscht WordPress die Datei wieder. Bricht der Vorgang ab, etwa weil PHP an das Zeitlimit stößt, der Speicher voll ist oder Sie das Browserfenster während eines Sammel-Updates schließen, bleibt sie liegen.

Wichtig für die Einordnung: Ist der Zeitstempel älter als zehn Minuten, ignoriert WordPress die Datei. Im Test mit einem 700 Sekunden alten Zeitstempel lieferte die Website wieder normal aus. Ein Wartungsmodus, der länger als zehn Minuten anhält, deutet daher auf eine Datei mit abweichendem Inhalt hin, meist ein Plugin oder eine manuell angelegte Datei (siehe Schritt 6).

Verifizieren: Rufen Sie die Kopfzeilen der Startseite ab. Im Wartungsmodus lautet die erste Zeile HTTP/1.1 503 Service Unavailable, dazu erscheint Retry-After: 600:

curl -sI https://www.example.com/ | head -5

Schritt 2: Zehn Minuten abwarten und Ursache eingrenzen

Sehen Sie die Wartungsmeldung direkt nach einem Update, warten Sie zunächst ab. Wer die Datei während eines laufenden Updates löscht, macht eine halb kopierte Installation für Besucher sichtbar.

Bleibt die Meldung nach zehn Minuten bestehen, gibt es zwei Möglichkeiten. Entweder hat ein Cache vor WordPress die 503-Seite gespeichert, oder die Datei .maintenance enthält keinen gültigen Zeitstempel. WordPress selbst sendet auf der Hinweisseite Header gegen Zwischenspeicherung (im Test Cache-Control: no-cache, must-revalidate, max-age=0, no-store, private). Ein falsch konfigurierter Seiten-Cache oder ein CDN kann die Seite trotzdem ausliefern. Rufen Sie die Seite deshalb mit einem angehängten Parameter auf, etwa ?nocache=1, oder leeren Sie den Cache im Hoster-Menü.

Verifizieren: Kommt auch mit Parameter noch 503, liegt die Ursache auf dem Server. Kommt 200, ist nur der Cache betroffen und die Website selbst läuft.

Schritt 3: Die Datei .maintenance entfernen

Der offizielle Weg laut WordPress-Dokumentation ist schlicht: Datei .maintenance im Hauptverzeichnis löschen. Je nach Zugang gibt es drei Varianten.

Per SFTP oder FTP: Verbinden Sie sich mit dem Webspace und wechseln Sie in den Ordner, in dem wp-config.php liegt. Dateien, deren Name mit einem Punkt beginnt, gelten unter Linux als versteckt. Viele FTP-Programme und Dateimanager blenden sie ohne Zusatzeinstellung aus. Aktivieren Sie in Ihrem Programm die Anzeige versteckter Dateien, dann erscheint .maintenance neben .htaccess. Löschen Sie nur diese eine Datei.

Per SSH:

cd /pfad/zu/wordpress
ls -la .maintenance
cat .maintenance
rm .maintenance

Steht in der Datei ein Zahlenwert, stammt sie vom WordPress-Updater. Steht dort etwas anderes, hat ein Plugin oder eine Person sie angelegt: Klären Sie dann, wer die Wartung geplant hat.

Per WP-CLI:

wp maintenance-mode status
wp maintenance-mode deactivate

Im Test lieferte der Befehl die Ausgabe „Success: Deactivated Maintenance mode.“ WP-CLI löscht dabei genau die Datei .maintenance. Achtung: WP-CLI meldet bei einer abgelaufenen Datei „Maintenance mode is not active.“ und verweigert das Deaktivieren mit „Error: Maintenance mode already deactivated.“, obwohl die Datei noch existiert. Harmlos, weil WordPress sie ebenfalls ignoriert; aufräumen können Sie dann nur mit rm oder per FTP.

Verifizieren: ls -la .maintenance meldet „No such file or directory“, und curl -sI auf die Startseite liefert wieder 200 oder eine Weiterleitung (301/302) statt 503.

Schritt 4: Nach dem Abbruch die Installation prüfen

Die Wartungsdatei zu löschen beseitigt nur das Symptom. Ist ein Update mitten im Kopieren abgebrochen, können WordPress-Dateien oder Plugin-Dateien in einem gemischten Zustand aus alter und neuer Version vorliegen. Mit WP-CLI vergleichen Sie die Dateien mit den offiziellen Prüfsummen von wordpress.org:

wp core verify-checksums
wp plugin verify-checksums --all

Im Test lautete die Ausgabe bei unveränderter Installation „Success: WordPress installation verifies against checksums.“ und „Success: Verified 2 of 2 plugins.“. Warnungen wie „File should not exist“ betreffen zusätzliche Dateien und sind separat zu bewerten. Premium-Plugins außerhalb von wordpress.org lassen sich so nicht prüfen; installieren Sie diese bei Verdacht aus dem Herstellerkonto neu.

Meldet die Prüfung abweichende Dateien im Kern, wiederholen Sie das Update. Legen Sie vorher ein Backup an, denn beim erneuten Update ersetzt WordPress Dateien. Im Backend finden Sie dafür unter Dashboard → Aktualisierungen die Schaltfläche „Version 7.1.2 neu installieren“ bzw. „Auf Version … aktualisieren“. Auf der Kommandozeile erledigt das wp core update --force für dieselbe Version.

Ohne SSH aktivieren Sie zur Fehlersuche das Debug-Log, wie in der Anleitung WordPress Debug-Modus aktivieren und Error-Logs analysieren beschrieben. Dort erkennen Sie, welches Plugin nach dem Abbruch einen Fehler wirft.

Verifizieren: Beide Prüfbefehle enden mit „Success“. Im Backend zeigt Dashboard → Aktualisierungen keine offenen Aktualisierungen mehr, und unter Werkzeuge → Website-Zustand erscheinen keine neuen kritischen Probleme.

Schritt 5: Updates so einspielen, dass der Modus nicht hängen bleibt

Die häufigsten Auslöser für einen abgebrochenen Updater sind zu knappe PHP-Limits, volle Datenträger und Sammel-Updates vieler Plugins auf einmal. Drei Gewohnheiten reduzieren das Risiko deutlich:

• Plugins in kleinen Gruppen oder einzeln aktualisieren statt alle gleichzeitig. Der Wartungsmodus gilt dann jeweils nur kurz, und ein Fehler lässt sich einem Plugin zuordnen.
• Vor großen Updates freien Speicher prüfen. WordPress entpackt das Paket zunächst in wp-content/upgrade/ und braucht dafür zusätzlichen Platz.
• Während eines Updates das Browserfenster nicht schließen.

Updates, Kontrolle nach dem Update und ein funktionierendes Backup sind keine einmalige Aufgabe, sondern kehren jede Woche wieder. Wer diese Arbeit nicht selbst im Kalender halten möchte, kann sie abgeben: Die WordPress-Wartung von wordpressupdate.de übernimmt Updates von WordPress, Plugins und Themes mit Kompatibilitätsprüfung, wöchentliche Backups auf externen Speicher mit vier Wochen Aufbewahrung und die Einrichtung und Wartung der Firewall.

Automatische Hintergrund-Updates starten zuverlässiger über einen echten Cronjob, siehe WordPress Cron Job einrichten.

Verifizieren: Nach dem nächsten Update liegt im Installationsverzeichnis keine Datei .maintenance mehr (ls -la im Ordner), und wp maintenance-mode status meldet „Maintenance mode is not active.“

Schritt 6: Den Wartungsmodus gezielt für eigene Arbeiten nutzen

Für kurze Eingriffe, etwa das Einspielen einer Datenbanksicherung oder einen Wechsel des Themes auf der Kommandozeile, können Sie den eingebauten Modus selbst schalten:

wp maintenance-mode activate
# Arbeiten durchführen
wp maintenance-mode deactivate
wp maintenance-mode is-active; echo $?

Der Befehl is-active gibt nichts aus, liefert aber einen Rückgabewert: 0 bei aktivem Wartungsmodus, 1 bei inaktivem. Zwei Eigenschaften sollten Sie kennen, bevor Sie den Modus einsetzen:

• Der Zeitstempel verfällt nach zehn Minuten. Dauert Ihre Arbeit länger, ist die Website danach wieder öffentlich, ohne dass Sie etwas tun. Für längere Arbeiten schalten Sie zwischendurch mit deactivate und activate neu.
• Das Backend ist ebenfalls gesperrt. Arbeiten, die Sie im Browser unter /wp-admin/ erledigen wollen, sind mit diesem Modus nicht möglich. Er taugt nur für Arbeiten per SSH, WP-CLI oder FTP.

Im Netz finden sich Empfehlungen, in .maintenance statt einer festen Zahl time() einzutragen, damit der Modus dauerhaft gilt. Das funktioniert, hat im Test aber zwei Nebenwirkungen: Die Sperre endet erst mit dem Löschen der Datei, und WP-CLI erkennt den Zustand nicht. Es meldet „Warning: Unable to read the maintenance file timestamp, non-numeric value detected.“ und behauptet „Maintenance mode is not active.“, während Besucher 503 erhalten. Verwenden Sie diese Variante deshalb nicht auf Produktivsystemen.

Die Hinweisseite selbst lässt sich mit einem sogenannten Drop-in anpassen: WordPress lädt statt der Standardmeldung die Datei wp-content/maintenance.php, wenn sie existiert, und führt sie in der Pluginliste als Drop-in mit der Beschreibung „Individuelle Wartungsmodus-Nachricht“. Die Datei muss den Statuscode selbst setzen. Im Test lieferte ein Drop-in ohne eigenen Header den Status 200, was Suchmaschinen eine leere Seite als regulären Inhalt meldet. Ein minimales Beispiel:

<?php
http_response_code( 503 );
header( 'Retry-After: 600' );
header( 'Content-Type: text/html; charset=utf-8' );
?>
<!doctype html>
<html lang="de">
<meta charset="utf-8">
<title>Wartungsarbeiten</title>
<h1>Wir sind in wenigen Minuten zurück.</h1>
<p>Bei dringenden Anliegen erreichen Sie uns telefonisch.</p>
</html>

Der Status 503 zeigt nach HTTP-Standard eine vorübergehende Nichtverfügbarkeit an, Retry-After nennt die Wartezeit in Sekunden. Halten Sie das Drop-in bei reinem HTML, es läuft vor dem Laden von Theme und Plugins.

Verifizieren: Nach wp maintenance-mode activate liefert curl -sI den Status 503 mit Ihrem Retry-After-Wert, der Seiteninhalt zeigt Ihren Text. wp plugin list --status=dropin führt maintenance.php auf. Nach deactivate antwortet die Website wieder normal.

Typische Fehler

Häufige Fragen

Schadet der Wartungsmodus der Platzierung bei Suchmaschinen?

Ein kurzer Wartungsmodus mit Status 503 und Retry-After signalisiert eine vorübergehende Störung, genau dafür ist der Statuscode gedacht. Problematisch sind tagelange Sperren oder eine Wartungsseite mit Status 200.

Kann ich im Wartungsmodus als Administrator weiterarbeiten?

Mit dem eingebauten Modus nicht: Im Test antworteten auch /wp-admin/ und /wp-login.php mit 503. Wer im Backend arbeiten und Besucher gleichzeitig aussperren will, braucht dafür ein Plugin, das angemeldete Nutzer ausnimmt, oder arbeitet auf einer Staging-Kopie.

Wo liegt .maintenance bei einer Installation in einem Unterordner?

Immer im WordPress-Installationsverzeichnis, also neben wp-load.php. Liegt WordPress in /blog/, suchen Sie dort und nicht im Webroot.

Testumfang

Wir haben das Aktivieren, Abfragen und Deaktivieren per WP-CLI in einer lokalen Testumgebung mit WordPress 7.1.2 durchgespielt. Dabei haben wir auch die zurückgegebenen Statuscodes und das Verhalten bei einem abgelaufenen Zeitstempel geprüft.

Abgebrochene echte Updates, Seiten-Caches und CDNs sowie Multisite haben wir nicht getestet. Wenn Sie so etwas einsetzen, probieren Sie das Vorgehen bitte zuerst auf einer Kopie Ihrer Website aus.

Fazit

Ein hängengebliebener Wartungsmodus ist in den meisten Fällen in zwei Minuten behoben: Datei .maintenance löschen, danach mit den Prüfsummen kontrollieren, ob das abgebrochene Update Spuren hinterlassen hat. Der zweite Teil ist der wichtigere, denn ein halb eingespieltes Update fällt sonst erst später auf. Für eigene Arbeiten per Kommandozeile ist der eingebaute Modus brauchbar, solange Sie das Zeitlimit von zehn Minuten und das gesperrte Backend einplanen. Wenn Sie Updates und die Kontrolle danach nicht selbst übernehmen möchten, übernimmt das die WordPress-Wartung von Marcel Schönfelder.

Weiterführende Anleitungen und Quellen

• WordPress Debug-Modus aktivieren: Error-Logs analysieren und Fehler selbst beheben
• WordPress Cron Job einrichten: WP-Cron durch echten System-Cron ersetzen
• Backup-Restore-Test als feste Routine etablieren
• WP-CLI-Handbuch: wp maintenance-mode
• Code-Referenz: wp_maintenance()
• WordPress Advanced Administration: Common WordPress errors