Briefly unavailable for scheduled maintenance: een vastgelopen WordPress-update oplossen

Je bezoekers zien een kale pagina met één zin: "Briefly unavailable for scheduled maintenance. Check back in a minute." Normaal flitst die melding voorbij in een paar seconden tijdens een update. Staat hij er al langer dan tien minuten? Dan is je site echt vastgelopen en moet je zelf even ingrijpen.

Wat die melding eigenlijk betekent

WordPress staat in onderhoudsmodus omdat er een bestand met de naam .maintenance in je site-root staat (de map waarin ook wp-config.php staat). Terwijl de update draait, stuurt WordPress een HTTP 503 terug met die melding en een Retry-After: 600 header, waarmee het de browser vertelt: probeer het over tien minuten nog eens. Zolang dat bestand er staat en de tijdstempel erin nog recent is, krijgt elke bezoeker dat onderhoudsscherm te zien in plaats van je site.

Het werkt vrij simpel. Zodra een update start, schrijft WP_Upgrader::maintenance_mode() een piepklein PHP-bestand dat er zo uitziet:

<?php $upgrading = 1735838412; ?>

Dat getal is de Unix-timestamp van het moment waarop de update begon. Loopt alles goed, dan verwijdert WordPress het bestand zodra de update klaar is. De onderhoudsmodus staat weer uit. Je site is terug.

Waarom WordPress zichzelf meestal redt, en wanneer het misgaat

WordPress heeft hier een noodrem voor ingebouwd. De functie wp_is_maintenance_mode() leest de $upgrading-tijdstempel en beschouwt het bestand als verouderd zodra die ouder is dan tien minuten: ( time() - $upgrading ) >= 10 * MINUTE_IN_SECONDS. Wacht je dus tien minuten en is de melding dan weg? Dan heeft WordPress het zelf opgelost en kun je direct door naar de preventietips.

Die noodrem heeft alleen één blinde vlek. Als WordPress het .maintenance-bestand wel heeft kunnen schrijven maar de update daarna zo hard crasht dat de opruimstap nooit uitgevoerd wordt, blijft het bestand gewoon op je server staan. Je bezoekers blijven een 503 krijgen totdat jij dat bestand weghaalt. In de praktijk zie je de fout vrijwel altijd terwijl de tijdstempel nog vers is, dus die 10-minutenregel trapt zelden op tijd in voordat jij aan het uitzoeken slaat.

Als je dit aan het lezen bent, staat het bestand er vrijwel zeker nog en moet je het handmatig weghalen.

De meest voorkomende oorzaken, op volgorde van waarschijnlijkheid

1. De update veroorzaakte een fatale PHP-fout. Een zojuist bijgewerkte plugin of thema gooide een fatale fout bij de activatie, waardoor WP_Upgrader nooit toekwam aan de stap "maintenance mode uitschakelen". Verreweg de meest voorkomende oorzaak. Vaak zie je na het verwijderen van het bestand meteen een andere foutmelding verschijnen. Zie mijn artikel over "There has been a critical error on this website" als dat gebeurt.
2. Je hebt tijdens de update ververst, het tabblad gesloten of doorgeklikt. Het sluiten van het browser-tabblad stopt de update op zich niet (die draait op de server), maar ongeduldige klikken en handmatige wp-admin-verversingen kunnen er wel toe leiden dat WordPress de afrondingsstap mist.
3. Een parse error in een bijgewerkte plugin of thema. Staat er in de nieuwe versie van een plugin of thema een PHP-syntaxisfout, dan kan het PHP-proces halverwege de update doodgaan en blijft .maintenance stranden.
4. Een PHP-timeout of out-of-memory tijdens de update. Goedkope shared hosts met strakke max_execution_time of lage memory_limit kunnen het updateproces halverwege afkappen, vooral wanneer je een grote plugin bijwerkt of core, meerdere plugins én thema's tegelijk installeert.
5. Een rechtenprobleem op het bestandssysteem. Kon WordPress .maintenance wel schrijven maar niet verwijderen (bijvoorbeeld omdat de eigenaar van de map is veranderd of omdat je SFTP-gebruiker andere rechten heeft dan de webserver-gebruiker), dan blijft het bestand staan terwijl de update zelf gewoon goed liep.

Welke oorzaak ook van toepassing is, de fix is hetzelfde. Haal het bestand weg, kijk wat eronder zit en los op wat daar wacht.

Eerst even diagnosticeren

Voordat je het bestand verwijdert, is het handig om te controleren of je wel het juiste probleem te pakken hebt.

• Kijk in de developer tools van je browser. Open het tabblad Network en herlaad de pagina. Het hoofddocument hoort HTTP 503 terug te geven met de tekst "Briefly unavailable for scheduled maintenance. Check back in a minute." Zie je een 500, een andere foutpagina of een wit scherm? Dan heb je waarschijnlijk een ander probleem te pakken, zoals een kritieke fout of een generieke 503 door een overbelaste server.
• Wacht één minuut en herlaad. Echte updates zijn meestal in een paar seconden klaar. Zie je de melding na 60 seconden nog steeds? Dan zit het bestand er gewoon vast. Niet urenlang wachten in de hoop dat het goed komt; die 10-minuten-regel is het langste dat het vanzelf zou duren.
• Check de statuspagina van je hostingprovider. Als je host zelf onderhoud uitvoert, kan de 503 van hun kant komen in plaats van van WordPress. In dat geval staat er geen .maintenance-bestand in jouw site-root om te verwijderen.

Komt de 503 echt uit het .maintenance-bestand? Door naar de oplossing.

De fix: verwijder het .maintenance-bestand

Je hebt bestandsbeheer nodig voor de root van je WordPress-installatie: de map waarin wp-config.php, wp-settings.php en wp-content staan. Bij de meeste hosts is dat public_html of een submap daarvan. Kies de methode die past bij de toegang die je hebt.

Methode A: SFTP

1. Maak verbinding met de server via je SFTP-client (FileZilla, Cyberduck, Transmit of iets vergelijkbaars) met je SFTP-gegevens van de host.
2. Navigeer naar de root van je WordPress-installatie. Je herkent 'm aan wp-config.php in de lijst. Zie je dat bestand niet? Dan zit je in de verkeerde map.
3. Zet verborgen bestanden tonen aan. In FileZilla vind je dat onder Server → Verborgen bestanden geforceerd tonen. Het .maintenance-bestand begint met een punt en is dus standaard verborgen.
4. Klik met rechts op .maintenance en kies Verwijderen.
5. Herlaad je website in de browser.

Je weet dat het gelukt is als: je homepage normaal laadt (of een andere foutmelding toont, wat betekent dat het onderhoudsscherm een dieperliggend probleem verborg). De 503-status is verdwenen uit het Network-tabblad.

Methode B: bestandsbeheer van het hosting control panel (cPanel, DirectAdmin, Plesk)

1. Log in op je hosting control panel en open File Manager.
2. Ga naar de WordPress-root (meestal public_html of de site-specifieke map bij DirectAdmin en Plesk).
3. Zet verborgen bestanden aan. In cPanel File Manager klik je rechtsboven op Settings en vink je Show Hidden Files (dotfiles) aan. In DirectAdmin en Plesk werkt het vergelijkbaar.
4. Selecteer .maintenance en klik op Verwijderen. Bevestig.
5. Herlaad je website.

Je weet dat het gelukt is als: de site weer een normale pagina toont en de 503 weg is. Zie je nu een kritieke fout? Dan is het onderliggende updateprobleem zichtbaar geworden en kun je dáár gericht op door.

Methode C: SSH met WP-CLI

Heb je SSH-toegang en is WP-CLI geïnstalleerd? Dit is de snelste manier.

1. Log in op je server via SSH.
2. Ga naar de WordPress-root: cd /var/www/jouwsite.nl/public (pas het pad aan naar je installatie).
3. Draai wp maintenance-mode deactivate. Dit verwijdert het .maintenance-bestand.
4. Herlaad je website.

De verwachte output is:

Success: Disabled Maintenance mode.

Krijg je Warning: Maintenance mode already disabled. te zien? Dan was het bestand al weg. Meestal betekent dat dat de 10-minutentimer net afliep, of dat de 503 die je zag ergens anders vandaan kwam.

Je weet dat het gelukt is als: wp maintenance-mode status teruggeeft Maintenance mode is disabled. en je browser je site weer normaal laadt.

Wat te doen als het weghalen van het bestand niet genoeg is

Meestal is je site direct terug. Zo niet, dan was dat .maintenance-bestand alleen het topje. Er is iets dieper vastgelopen tijdens de update en dat komt nu bovendrijven in plaats van de onderhoudsmelding.

• Zie je nu "There has been a critical error on this website"? Werk dan mijn stappenplan voor die melding door. Een zojuist bijgewerkte plugin of thema is vrijwel altijd de dader.
• Krijg je een parse error of een wit scherm met een PHP-foutmelding? Volg dan mijn troubleshooting-artikel over "syntax error, unexpected". De nieuwe versie van een plugin of thema is uitgebracht met kapotte PHP voor jouw versie.
• Keert de site elke paar minuten terug naar onderhoudsmodus? Dan staat er een geplande auto-update die telkens opnieuw faalt. Hernoem de map van de problematische plugin in wp-content/plugins/ om 'm uit te schakelen en herlaad de site. De volledige diagnostische walkthrough voor herhaaldelijk gefaalde automatische updates staat in een automatische WordPress-update is mislukt: zo herstel je veilig.
• Verschijnt .maintenance binnen seconden weer vanzelf? Dan is iets op je server dat bestand aan het terugschrijven. Dit komt niet vaak voor, maar het gebeurt soms bij verkeerd geconfigureerde multisite-installaties of wanneer de "under attack"-modus van een security-plugin een vergelijkbaar bestand aanmaakt. Schakel de security-plugin uit door de map te hernoemen en probeer opnieuw.

Wanneer je hulp inschakelt

Heb je het .maintenance-bestand verwijderd, de pagina herladen, gewacht en doet de site het nog steeds niet? Dan is het tijd om hulp in te schakelen. Verzamel eerst deze informatie voordat je een ticket opent:

• De exacte URL en de exacte foutmelding die je nu ziet (niet de originele onderhoudsmelding).
• Je WordPress-versie, je PHP-versie en het actieve thema.
• De plugin of plugins die werden bijgewerkt toen het probleem begon, met hun versies van vóór en ná de update.
• De tijdstempel die in het .maintenance-bestand stond voordat je het weggooide. Open het bestand dus éérst even: het bevat een regel als <?php $upgrading = 1735838412; ?> die precies aangeeft wanneer de update begon. Voor een support engineer is dat het nuttigste stukje context dat je kunt aanleveren.
• Wat er in wp-content/debug.log staat van het afgelopen uur (als WP_DEBUG_LOG aan stond).
• Het error log uit je hosting control panel voor datzelfde tijdvenster (cPanel, DirectAdmin en Plesk hebben er allemaal één).
• Een lijstje van de stappen die je uit dit artikel al hebt geprobeerd.

Stuur dat naar je host, je developer of je managed WordPress-provider. Een goede support engineer prikt er met die informatie in een paar minuten doorheen.

Hoe je deze situatie voortaan voorkomt

• Ververs of sluit het WordPress-beheertabblad niet terwijl een update loopt. De update draait op de server, niet in je browser, maar rondklikken in het dashboard midden in een update kan ervoor zorgen dat WordPress de afrondingsstap mist. Wacht gewoon tot het "Updates have been completed"-scherm verschijnt.
• Update in kleinere batches. Core, twintig plugins en drie thema's in één klik bijwerken is precies het scenario waarin PHP-timeouts en memory limits je te pakken nemen. Doe eerst core, daarna plugins in groepen van vijf en tot slot de thema's.
• Test plugin- en thema-updates eerst op een staging-site. Een beetje fatsoenlijke host biedt een staging-omgeving met één klik. Een dozijn plugins bijwerken op staging brengt fatale fouten aan het licht voordat je bezoekers er iets van merken.
• Zorg voor backups die draaien vlak vóór een update. Zowel UpdraftPlus als de ingebouwde backup bij goede managed hosting kan een backup triggeren vlak voor een automatische update, zodat je met één klik kunt terugzetten als er iets breekt.
• Verhoog max_execution_time en memory_limit als je grote plugins bijwerkt. Sites met pagebuilders, WooCommerce of een learning management plugin hebben vaak minstens max_execution_time = 300 en memory_limit = 512M nodig om schoon te updaten. Laat je host die waardes niet aanpassen? Dan is dat een signaal om eens naar een ander pakket te kijken.
• Zet automatische updates uit voor plugins die regelmatig problemen geven. Een stabiele plugin die twee keer crasht bij een update is het risico van een 3 uur 's nachts-downtime niet waard. Schakel auto-updates voor die plugin uit via Plugins → Geïnstalleerde plugins en update 'm handmatig doordeweeks.

De onderhoudsmelding zelf is onschuldig. Hij wordt pas een probleem zodra een update sneuvelt vóór de opruimstap, en de oplossing is bijna altijd dezelfde: één bestand weghalen en daarna uitzoeken wat eronder is kapotgegaan.