Technote

Servers & infrastructure Intro

Series The incident runbook Part 2 of 8

The white screen: send errors to a log, never to the screen

A blank screen is not an absence of information, it is hidden information. Turning on logging usually names the cause in one line — turning it on to the screen is the accident.

A blank screen is almost always a PHP fatal error: execution stopped part-way through, nothing was printed, and the browser rendered the empty response. The status code is either 200 or 500.

It looks like an absence of information, but the information is hidden rather than missing. Production defaults keep errors off the screen, and that default is correct — the job is not to switch it off but to change the destination to a file.

1. Turn logging on — to a file, not the screen

Add these above the /* That's all, stop editing! */ line in wp-config.php. The three go together, and the last one matters most.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );    // writes to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // never render errors to the browser

There are two reasons never to display errors on a live site. First, the messages carry absolute server paths, database names and the call flow — a map handed straight to anyone probing you. Second, visitors and search engines see that screen.

Identical error detail — the destination decides whether it is a diagnosis or an incident

2. Keep the log file out of the web root

By default wp-content/debug.log is readable over the web. Having just stopped errors reaching the screen, you would be publishing the same content at a fixed URL. Block it when you enable debugging, and move the log outside the document root if you can.

location ~* .(log|sql|bak)$ { deny all; }

And turn it back off once you have the answer. Leaving debug logging on is extremely common, the file keeps growing, and eventually it fills the disk — which becomes the outage covered in part five.

3. Read the log from the bottom

However long the file is, you want one thing: the Fatal error line at the moment the outage began. It carries the error type and a file path, and the path names the culprit.

From one fatal line to the next action — the path decides the response

If the message mentions Allowed memory size, you have hit the memory limit. Raising it will get you back online, but a site that worked yesterday and exceeds the limit today has something newly consuming much more, so investigate separately. Raising the limit is a mitigation, not a fix.

If even the admin will not load, check for the recovery mode email WordPress sends. When core catches a fatal error it emails the administrator the offending plugin and a recovery link — which only arrives if your mail sending works, and that is why checking mail delivery is part of being ready for an outage.

Setting all of this up before you need it is covered in the Servers & infrastructure archive, and logging, permissions and caching are configured together as part of our optimization program.

Next part

You turned logging on and now there are several logs. The next part covers what the PHP, web server and MySQL logs each tell you, and the order to read them in.

More on this topic

All technotes

Servers & infrastructure Practical

Stop PHP from running in the uploads directory

A file landing and a file executing are two different steps. One setting between them keeps an upload problem a cleanup job.

Site operators 7 min read

Servers & infrastructure Practical

A full disk breaks a site in confusing ways

A textbook case of symptoms that do not point at the cause. Knowing what fills a disk makes it a three-minute hunt — and reclaiming space has a…

Site operators 10 min read

Servers & infrastructure Practical

Production error logs: to a file, never to the screen

Displaying errors leaks your internals to visitors; leaving the log inside the web root leaks them to anyone who guesses the URL. Those two sentences are the whole…

Developers 9 min read

₩270,000 · Join the program