Why a WordPress debug log beats showing errors on screen
When WordPress hits a serious PHP error, the default behaviour is to show a blank page or a short critical error message. Visitors see nothing useful, and neither do you. The real cause sits underneath, in a message that PHP generated and then kept to itself.
WordPress has a built-in debug mode that brings those messages out. Turned on carelessly, though, it prints errors, warnings and notices directly into your pages, where customers and anyone else browsing can read file paths and details about your plugins. A log file gives you the same information while keeping the public pages quiet.
The WordPress Advanced Administration Handbook provides the configuration for exactly this split: write everything to a file, hide it from the page. If you are working through a blank page, our guide to the white screen of death explains what to collect alongside the log.
Before you edit wp-config.php: back up and prefer staging
All of the debug settings live in wp-config.php, the file that also holds your database connection details. One misplaced character there can take the whole site offline, so take a backup before you open it.
WordPress guidance on backups treats a site as two parts: the files and the database. Backing up the files alone does not capture the database, so make both, ideally around the same time so they belong together as one set. A copy of wp-config.php saved to your computer before you edit gives you the quickest way back if the change goes wrong.
The handbook also recommends using debug tools on local or staging copies rather than live sites. If your host offers a staging copy and the fault appears there too, debug on staging. Some faults only show up on the live site, and in that case keep the live debugging window as short as possible.
Turn on the WordPress debug log in four steps
Open wp-config.php through your host's file manager or an SFTP client. Near the bottom you will find a comment that says That's all, stop editing! Happy blogging. Everything below must go above that line, or WordPress will not pick it up. If your file already contains a line defining WP_DEBUG, edit that line rather than adding a second one.
Each setting follows the same define format used in the handbook example, and the values true and false go in without quotation marks. Quoting a value turns it into text, and WordPress reads the text 'false' as true, which is a common way to leave debugging switched on by accident.
- Save a copy of the current wp-config.php so you can restore it in seconds.
- Above the stop-editing line, add a line that defines WP_DEBUG as true to switch on debug mode. The other two settings do nothing without it.
- Add a line that defines WP_DEBUG_LOG as true so errors are written to debug.log in the content directory, wp-content/debug.log on a standard install.
- Define WP_DEBUG_DISPLAY as false and set the PHP display_errors option to 0, as the handbook example does, so messages stay out of your pages, then save the file and load the homepage to confirm the site still works.
Reproduce the fault and read debug.log
Logging only captures what happens after you switch it on, so now trigger the problem. Load the page that went blank, submit the form that fails, or repeat the checkout step that throws an error. Note the time you did it, because each log entry carries a timestamp and you will want to match your action to the right lines.
Download wp-content/debug.log and open it in a plain text editor. Start at the most recent entries. A line beginning PHP Fatal error is the strongest lead, and the file path in that line names the plugin or theme folder where the failure happened. Warnings, notices and deprecation messages appear too; they point to code that needs tidying, yet they rarely explain a full outage on their own.
The log also records problems that never appear on screen, such as errors during background requests and scheduled tasks. That makes it useful for admin buttons that spin and fail, which our page on admin-ajax.php errors covers in more detail. For a fuller walkthrough of finding and interpreting the file, see our step-by-step debug logging guide.
Switch debugging off and deal with the log file
Once you have the entries you need, set WP_DEBUG back to false, or restore the copy of wp-config.php you saved earlier. Load a few pages afterwards to confirm the site behaves as it did before you started.
Leaving debugging on carries two costs. The log keeps growing for as long as errors occur, and some optional settings slow the site down: the handbook warns that SAVEQUERIES has a performance impact and should be turned off when you are not debugging. If you or a developer added it, remove it at the same time.
The log file itself deserves attention. On a standard install it sits inside wp-content, alongside folders that serve public files. Do not assume it is private. Ask your host whether debug.log can be fetched directly in a browser and how they block it. WP_DEBUG_LOG also accepts a file path instead of true, so your host can suggest a location outside the public web folder. When you are finished, download what you need and delete the file from the server.
Checking the fix: observation versus proof
A page that loads again after a change is an observation, not proof of the cause. Caches expire, scheduled tasks finish and intermittent faults go quiet for hours, so a working site on its own does not confirm which change mattered.
Stronger evidence comes from repeating the test. Delete or empty debug.log, keep logging on briefly, and perform the same action that failed before. If the specific fatal error you identified no longer appears and the action completes, you have a direct link between the fix and the result. If the error returns at random, the trigger is still active and the log entries will show when.
When the log points at a plugin you recently updated, our guide to update WordPress plugins safely explains how to roll back and test properly. If the entries make little sense or the site stays down, our team handles WordPress error fixes with confirmed pricing, and a blank site can go straight to the white screen fix service.
Sources
WordPress debug log FAQs
Where does WordPress save the debug log?
With WP_DEBUG_LOG set to true, WordPress writes to debug.log in the content directory, which is wp-content/debug.log on a standard install. You can set WP_DEBUG_LOG to a file path instead if you want the log stored somewhere else.
Why is debug.log empty after I turned logging on?
Check that WP_DEBUG is true, because WP_DEBUG_LOG does nothing without it, and that your lines sit above the stop-editing line. Then reproduce the fault, since the log only records errors that happen after logging starts.
Is it safe to run the WordPress debug log on a live site?
WordPress recommends debug tools for local and staging sites. If the fault only appears live, keep display off, keep the session brief, ask your host whether debug.log is publicly reachable and switch debugging off as soon as you have the entries.
Why did my errors still appear on the page?
WP_DEBUG_DISPLAY defaults to true, so it must be set to false, without quotation marks. A quoted 'false' counts as text and WordPress treats it as true. Setting the PHP display_errors option to 0 as well matches the handbook example.
Should I delete debug.log when I have finished?
Yes, once you have downloaded the entries you need. Turn WP_DEBUG off first so the file is not recreated, then remove it from the server so old error details are not left sitting in wp-content.