Enable WordPress Debug Mode

Er is iets mis met je site, maar WordPress vertelt je niet wat. Een pagina blijft leeg, een knop doet niets of je krijgt alleen de melding dat er een kritieke fout is opgetreden. De WordPress debug-modus schakel je in door in wp-config.php de constanten WP_DEBUG and WP_DEBUG_LOG on true te zetten en WP_DEBUG_DISPLAY on false, zodat fouten in wp-content/debug.log komen in plaats van op het scherm van je bezoekers. Hieronder lees je hoe je dat veilig doet, hoe je het logbestand leest en waarom je hem daarna weer uitzet.

Wat de debug-modus doet

De debug-modus is een instelling in WordPress die PHP-fouten, waarschuwingen en verouderde functieaanroepen zichtbaar maakt, inclusief het bestand en de regel waar het misgaat. Op een live site staat hij standaard uit. Dat is bewust, want een foutmelding kan bestandspaden of databasegegevens tonen die je niet op straat wilt hebben. Zet je hem aan, dan hoef je niet meer te gokken welke plugin het probleem geeft. Je leest het terug. Daarom is dit voor mij de eerste stap bij bijna elke fout zonder duidelijke melding, van een white screen of death tot de melding uit A critical error has occurred.

Er werken drie instellingen samen. WP_DEBUG zet het melden van fouten aan. WP_DEBUG_LOG bepaalt of die meldingen naar een logbestand gaan, en WP_DEBUG_DISPLAY of ze op de pagina zelf verschijnen. De juiste combinatie op een live site is dus debug aan, logging aan en weergave uit. Zo krijg jij de informatie en ziet je bezoeker gewoon de site, of in het slechtste geval dezelfde fout als ervoor. Kom je nog in het dashboard, kijk dan ook bij Gereedschap > Sitediagnose. Onder het tabblad Info zie je de PHP-versie, het geheugenlimiet en of debug aan staat, en dat leg ik graag naast het log. Voor het bredere stappenplan bij fouten, van databaseverbinding tot offline site, kun je terecht in Troubleshooting WordPress Errors.

Zo zet je de debug-modus aan

Je zet de debug-modus aan door drie regels toe te voegen aan wp-config.php, het configuratiebestand in de hoofdmap van je WordPress-installatie. Een typefout in dit bestand haalt je site offline, dus werk rustig en bewaar eerst een kopie.

1. Open de File Manager in je hostingpaneel of maak verbinding via SFTP, en ga naar de hoofdmap van je site.
2. Download wp-config.php als reservekopie en open het bestand in de editor.
3. Zoek of er al een regel met WP_DEBUG staat. Pas die dan aan, want dezelfde constante twee keer definiëren geeft zelf een fout.
4. Zet boven de commentaarregel waarin staat dat je moet stoppen met bewerken deze drie regels define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); define('WP_DEBUG_DISPLAY', false);
5. Sla het bestand op en herhaal de handeling die misgaat.

Vanaf dat moment schrijft WordPress alles weg naar wp-content/debug.log. Het bestand verschijnt pas als er ook echt iets te melden is. Werk je op een testkopie, dan mag WP_DEBUG_DISPLAY daar gerust op true. Dan zie je fouten direct op het scherm terwijl je bouwt, en dat scheelt zoeken. Werk je met SSH, dan kan het zonder de editor. Met wp config set WP_DEBUG true --raw zet WP-CLI de waarde voor je, en die opdracht doe je ook voor de andere twee. Ben je niet gewend om in configuratiebestanden te werken, lees dan eerst WordPress-code bewerken. Daar leg ik uit hoe je zulke aanpassingen doet zonder je site te breken.

Het logbestand lezen

At debug.log zoek je naar regels met PHP Fatal error rond het tijdstip waarop je de fout zag, want dat zijn de meldingen die een pagina echt platleggen. Open het bestand en scroll naar onderen, daar staan de nieuwste regels. Elke regel noemt een tijdstip, het type melding en het pad naar het bestand. Aan dat pad zie je meestal direct de bron. Staat er wp-content/plugins/plugin-name/ in, dan is het die plugin. Staat er wp-content/themes/themanaam/ in, dan zit het in je thema.

Raak niet in paniek van een log vol meldingen. Een Notice or Deprecated is een signaal voor de maker van een plugin dat iets verouderd is, geen acute fout. Op veel sites staan er honderden en de site werkt prima. Een Warning verdient wel aandacht, maar breekt de pagina meestal niet. Vind je in debug.log niets, kijk dan ook in het foutlog van de server. Op onze hosting schrijft PHP fouten naar een bestand error_log in de map waar de fout optreedt. Daar vang je ook fouten die al optreden voordat WordPress zijn eigen logging start. Wil je zien welke verzoeken er rond dat tijdstip binnenkwamen, dan vind je de toegangslog in cPanel onder Raw Access.

Veilig werken en daarna weer uitzetten

Zet de debug-modus na je diagnose altijd weer uit, want het logbestand groeit door en staat standaard op een plek die iedereen kan opvragen. Dat laatste weten veel mensen niet. Wie het adres /wp-content/debug.log achter je domein typt, kan het bestand op veel servers gewoon lezen, inclusief paden en soms gegevens uit formulieren. Je hebt twee oplossingen. Je kunt het log op een andere plek laten schrijven door bij WP_DEBUG_LOG een pad buiten je publieke map op te geven in plaats van true, of je blokkeert het bestand met een regel in .htaccess. Voorbeelden van zulke regels staan in het .htaccess-bestand uitgelegd.

Ben je klaar, zet dan WP_DEBUG terug op false of verwijder de regels, en verwijder ook debug.log. Wil je dieper graven, dan zijn er nog twee schakelaars. SCRIPT_DEBUG laadt de onverkleinde scripts van WordPress, handig bij JavaScript-problemen, en SAVEQUERIES legt elke databasequery vast. Die laatste vertraagt je site, dus die hoort op een staging environment. Een plugin zoals Query Monitor maakt dezelfde informatie leesbaar en helpt bij het zoeken naar oorzaken uit een trage WordPress-site.

Wat we bij Surver op de shared pakketten bieden, is alles wat je hiervoor nodig hebt. Je hebt File Manager, SSH en WP-CLI, en die error_log-bestanden schrijft de server zelf. Op onze Managed WordPress Hosting doe je de diagnose zelf. Wil je dat iemand anders updates bijhoudt en ingrijpt als het misgaat, kijk dan naar WordPress maintenance. Kwam de fout direct na een update, dan staat de herstelroute in Site Down After an Update.

Frequently Asked Questions

Waarom wordt er geen debug.log aangemaakt?

Meestal staat WP_DEBUG_LOG niet op true, is WP_DEBUG verderop in het bestand nog een keer op false gezet, of staan de regels onder de regel waar je moet stoppen met bewerken. Het kan ook dat er simpelweg nog geen fout is opgetreden sinds je hem aanzette.

Vertraagt de debug-modus mijn site?

Een klein beetje, omdat elke melding naar schijf wordt geschreven. Op een site met veel meldingen merk je dat wel. Daarom zet je hem alleen aan voor de diagnose.

Kan ik de debug-modus aanzetten zonder wp-config.php te bewerken?

Ja, met WP-CLI via SSH of met een plugin die de constanten voor je zet. Bij een wit scherm werkt een plugin alleen niet, omdat je dan niet in het dashboard komt. Op Surver shared hosting zijn SSH en WP-CLI in alle pakketten beschikbaar.