Quick answer: To enable WordPress debug mode, edit wp-config.php and add define( 'WP_DEBUG', true );, define( 'WP_DEBUG_LOG', true ); and define( 'WP_DEBUG_DISPLAY', false ); above the line “That’s all, stop editing!”. WordPress will then write errors to wp-content/debug.log without showing them to visitors. Reproduce the problem, read the log, fix the cause and turn debugging off again.
What is WordPress debug mode?
Normally WordPress hides PHP errors so visitors don’t see technical messages. Debug mode makes those errors visible to you — either on screen or in a log file — so you can see exactly which plugin, theme or code line is causing a problem like a white screen, a broken feature or a critical error.
The debug settings explained
| Constant | What it does | Recommended on a live site |
|---|---|---|
WP_DEBUG | Turns debug mode on | Only temporarily |
WP_DEBUG_LOG | Saves errors to wp-content/debug.log (or a path you choose) | Yes, while debugging |
WP_DEBUG_DISPLAY | Shows errors on screen | No — set to false |
SCRIPT_DEBUG | Loads non-minified core CSS/JS | Only for developers |
SAVEQUERIES | Records database queries | No — slows the site |
How to enable debug mode (step by step)
- Back up
wp-config.php. - Open it with your host’s file manager or an SFTP client.
- Find the line
/* That's all, stop editing! Happy publishing. */. - Above it, add:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );- If
WP_DEBUGis already defined as false, change it to true instead of adding a duplicate. - Save the file and reproduce the problem (load the broken page or repeat the action).
Where to find and how to read debug.log
Open wp-content/debug.log. Each line has a time, an error type and a message with a file path and line number, for example:
PHP Fatal error: Uncaught Error: Call to undefined function example() in /wp-content/plugins/some-plugin/file.php:42| Error type | Meaning | Urgency |
|---|---|---|
| Fatal error | Code stopped running — often a white screen | High |
| Parse / syntax error | Broken code (missing bracket or semicolon) | High |
| Warning | Something went wrong but the page still loaded | Medium |
| Notice / Deprecated | Old or sloppy code; usually harmless | Low |
The file path tells you the culprit: /plugins/plugin-name/ points to a plugin, /themes/theme-name/ to a theme. Then follow our plugin troubleshooting steps or white screen fixes.
Turn debugging off when you’re done
Set WP_DEBUG back to false (or remove the lines) and delete debug.log. Leaving debug mode on can fill your disk with log entries, and a publicly accessible log could reveal file paths and other technical details to attackers. For extra safety you can log to a custom path outside the web root:
define( 'WP_DEBUG_LOG', '/home/youraccount/logs/wp-debug.log' );Example: finding the cause of a broken contact form
Imagine your contact form stops sending messages. You enable debug logging, submit the form once, and open debug.log. You see a line like “PHP Warning: Undefined array key in /wp-content/plugins/form-plugin/includes/mailer.php on line 210”, followed by another plugin’s file in the same request. That tells you the form plugin and a second plugin are clashing. You deactivate the second plugin on staging, the form works again, and you report the conflict to both developers with the exact error lines. Without the log, you might have spent hours guessing.
Common errors and what they usually mean
| Log message contains | Usually means |
|---|---|
| Allowed memory size exhausted | Increase WP_MEMORY_LIMIT or reduce heavy plugins |
| Call to undefined function | Missing plugin dependency or PHP version mismatch |
| Maximum execution time exceeded | A slow process — ask host to raise the limit or optimise |
| Headers already sent | Extra spaces or output in a PHP file, often functions.php |
Other ways to see errors
- Recovery mode email: WordPress emails the admin when a fatal error occurs, with a link to log in and pause the plugin or theme.
- Site Health: Tools → Site Health shows configuration problems.
- Host error logs: most hosting panels show PHP error logs.
- Debugging plugins: tools like Query Monitor show errors, slow queries and hooks inside the dashboard.
- Browser console: press F12 to see JavaScript errors.
Debugging safely on a live site
Whenever possible, debug on a staging site. If you must debug live, never display errors on screen, keep the time short and remove the log afterwards.
Frequently asked questions
Where is wp-config.php?
In your WordPress root folder, usually alongside wp-admin and wp-content.
Why is debug.log empty?
The problem may not be a PHP error (try the browser console), or the server may log elsewhere. Check the host’s error log.
Is it safe to leave WP_DEBUG on?
No — turn it off after troubleshooting.
What do “deprecated” notices mean?
Code is using something that will be removed in future. Update the plugin or theme when possible.
Final thoughts
Debug mode turns a mysterious problem into a clear error message. Enable logging, read the file path, fix the cause and switch it off. Official reference: Debugging in WordPress.
A real-world example
A blogger’s site began showing a critical error only on the contact page. Everything else worked. She added the three debug lines to wp-config.php, loaded the contact page once, then opened wp-content/debug.log. The last line read “PHP Fatal error: Uncaught TypeError” and pointed to a file inside a form add-on plugin. The add-on hadn’t been updated in two years and didn’t support the newer PHP version her host had switched to. She deactivated the add-on, replaced it with a maintained alternative and turned debugging off. Without the log, she might have spent hours guessing.
Debug logs and security
Debug logs can reveal file paths, plugin names and other details useful to attackers, so never leave them publicly accessible. Keep WP_DEBUG_DISPLAY set to false on live sites, delete debug.log when you’re finished, and turn WP_DEBUG off again. Some security incidents make logging more important, not less: after the October 2026 PHP2Shell vulnerabilities, hosts looked for patterns such as bursts of memory-limit errors and fatal errors in server logs to spot attack attempts. Your host’s server logs are often more useful than WordPress’s own log for security investigations — ask support for them if you suspect a problem.
Other useful debugging tools
- Query Monitor: a free plugin showing database queries, PHP errors, hooks and slow components on each page.
- Site Health: under Tools → Site Health, it flags configuration problems and shows server details.
- Browser developer tools: the Console and Network tabs reveal JavaScript errors and slow files.
Reading a PHP error line
Each error line in debug.log has the same parts: the date and time, the error type (Fatal error, Warning, Notice or Deprecated), a short message and the file path with a line number. Fatal errors stop the page and are the ones to fix first. Warnings and notices usually don’t break anything but are worth passing to the plugin’s developer. Deprecated messages mean the code uses something that will be removed in a future PHP or WordPress version — a sign the plugin needs updating soon.
Fix fatal errors first, then work through warnings when you have time.
WordPressPrime.com is an independent guide and is not affiliated with the WordPress Foundation, WordPress.org or Automattic. Always back up your website before making changes, and check official sources for the latest details.
