If your WordPress site throws mysterious errors, white screens, or strange behavior, turning on WordPress debug mode is the fastest way to see what’s going on. If you need immediate assistance, you can also check out emergency WordPress support for expert help. This guide walks you through every method to enable debugging, how to read logs, fix common issues, and keep your site secure while debugging. Always keep a recent backup, and if anything goes wrong, you can restore your WordPress site from backup manually.”
Why enable WordPress debug mode?
Debug mode surfaces the PHP notices, warnings, deprecated messages, and fatal errors that normally get hidden by default. Knowing the error message and file/line number usually takes you from “I have a problem” to “I can fix this” in minutes.
Use debug mode to:
-
Find plugin/theme conflicts.
-
Track down syntax errors or bad function calls.
-
See slow or duplicated database queries.
-
Debug AJAX/REST calls and JavaScript issues (with a few extra steps).
Important: Never leave full debug output visible on a public production site. We’ll show safe ways to log errors without exposing them to visitors.
Quick summary (for pros)
Add to wp-config.php (before /* That's all, stop editing! */):
Then check wp-content/debug.log. When you’re done, set WP_DEBUG to false.
Where to add debug settings (wp-config.php)
Always edit the root wp-config.php for the site (not theme files). Place your changes above the line:
Example full block:
What each constant does
-
WP_DEBUG— master switch (true/false). Enables debugging mode. -
WP_DEBUG_LOG— when true, writes errors towp-content/debug.log. -
WP_DEBUG_DISPLAY— controls whether errors are sent to the browser (true/false). Set tofalseon live sites. -
@ini_set( 'display_errors', 0 );— double-safesdisplay_errorsat the PHP level.
Safer: enable debugging for your IP only
To avoid showing errors to all visitors, enable display only for your IP address (helpful on staging or even restricted production access):
Tip: Replace 203.0.113.5 with your real public IP. To find it, visit whatismyip or check your router.
Turn on useful extras
Log database queries (slow — development only)
When SAVEQUERIES is true, WordPress stores each DB query in $wpdb->queries. You can inspect this array in templates or using a plugin like Query Monitor. Performance note: this increases memory usage and slows the site — don’t use on production.
Unminified scripts/styles (for JS/CSS debugging)
This forces WordPress to use non-minified copies of core assets (useful when debugging JS issues).
Where debug messages go
-
WP_DEBUG_LOGwrites towp-content/debug.logby default. -
If you set a custom PHP
error_logpath, errors may go elsewhere.
Check wp-content/debug.log after reproducing the issue. If it’s not created, see the file permissions section below.
File permissions and debug.log not writable
If wp-content/debug.log is missing or empty, ensure the webserver can write to it.
Create and set permissions (example for Linux — adjust user and group as needed):
If you can’t change owner, chmod 666 debug.log will work temporarily on shared hosts — but do not leave 666 set long-term.
Using WP-CLI to toggle debug constants
If you have WP-CLI:
To turn off:
WP-CLI edits the wp-config.php reliably and is safer than manual changes when available.
Debugging JavaScript and AJAX
-
Enable
SCRIPT_DEBUG(see above) to load unminified JS. -
Use browser DevTools Console and Network tab for JS errors and failed AJAX calls.
-
For jQuery/AJAX endpoints, check the response body in Network tab — server-side PHP errors will appear there if
WP_DEBUG_DISPLAYis on or if logged todebug.log.
To log server-side data during AJAX:
Then open wp-content/debug.log.
Debugging REST API calls
REST responses include HTTP status and JSON body. If responses are 500, check debug.log for PHP errors. You can also error_log() inside your REST callback to trace execution.
Using plugins to simplify debugging
-
Query Monitor — inspect queries, hooks, PHP errors, HTTP requests, and more (dev toolbelt).
-
Debug Bar (plus add-ons) — quick debugger in admin bar.
-
Log Deprecated Notices — logs deprecated function usage.
-
Health Check & Troubleshooting — isolate plugin/theme conflicts.
Plugins are great because they provide readable UIs, but remember: plugins themselves can conflict — use them on staging or local environments. If a plugin is causing fatal errors and you can’t access the dashboard, you can disable WordPress plugins without admin to regain access safely.
Example — interpret a common error
Example error in debug.log:
How to read:
-
The date/time is first.
-
Fatal errorshows the severity — fatal errors stop execution. -
Call to undefined function my_custom_function()points to a missing function (maybe a plugin is deactivated or file not included). -
The file and line (
functions.php:120) tells you where to inspect. -
Stack trace shows how execution reached that point.
Fix: open the theme file at line 120 — find the call to my_custom_function() and either include the file that defines it or wrap it with function_exists().
Common gotchas & solutions
-
No debug.log created: permissions issue; create file and set correct owner/permissions.
-
Errors still hidden on screen:
WP_DEBUG_DISPLAYor PHPdisplay_errorsmay be overridden by host-level php.ini — use@ini_set( 'display_errors', 1 );for dev, or check host control panel. -
Plugin or theme conflicts: use Health Check’s Troubleshooting mode (safe) or rename plugin folders to isolate problem.
-
White Screen of Death (WSOD): enable
WP_DEBUGandWP_DEBUG_LOG, checkdebug.logfor fatal errors. Often a plugin/theme update caused a PHP fatal error. -
Too many notices/warnings: often harmless but point to deprecated code. Fix by updating plugins/themes or suppress notices in production (
WP_DEBUG_DISPLAY = falseand log instead). -
Large logs: clear
debug.logperiodically with> debug.logorecho "" > debug.log. Don’t keep huge logs on production.
Advanced: custom logging and error handlers
You can direct PHP error logging to a custom file:
Use error_log() in code to write custom messages:
For structured logging, log JSON lines:
Debugging WordPress Cron (WP-Cron) and background tasks
WP-Cron runs on page loads. If scheduled tasks fail:
-
Check
debug.logfor cron-related errors. -
Manually run cron jobs and watch logs:
wp cron event run --due-now(WP-CLI). -
For real background jobs, consider running real cron triggering WP-CLI or using Action Scheduler tools.
When to use an error monitoring service
If you need continuous, searchable error tracking across environments (and real-time alerts), use services like Sentry, New Relic, or Bugsnag. They catch exceptions, group them, and notify you.
Turning debug off and cleaning up
When finished:
-
Set
WP_DEBUGback tofalse(or remove the debug lines). -
Remove or rotate
wp-content/debug.log(don’t leave logs that leak paths/errors). -
Reset file permissions if you changed them temporarily.
-
If you added
@ini_setlines, remove them.
Best practices checklist
-
✅ Debug on local or staging environments first.
-
✅ When debugging production, log errors to a file (not to the browser).
-
✅ Limit display to your IP if you must see errors in browser.
-
✅ Use Query Monitor to inspect DB queries and hooks.
-
✅ Remove debug code and rotate logs after fixing issues.
-
✅ Keep backups before editing theme/plugin files.
-
✅ Use version control (git) to track changes.
FAQ (short answers)
Q: How do I safely enable debugging on a live site?
A: Turn on WP_DEBUG and WP_DEBUG_LOG but set WP_DEBUG_DISPLAY to false. Log errors to wp-content/debug.log and restrict on-screen display to your IP if needed.
Q: Where is debug.log located?
A: By default it’s wp-content/debug.log. If your host redirects PHP errors, check php.ini settings or ask your host.
Q: Why is debug.log empty?
A: Common reasons: WP_DEBUG_LOG not enabled, file permission issues, or errors are being captured by host-level error log. Ensure WP_DEBUG and WP_DEBUG_LOG are true and debug.log is writable.
Q: Can I use WP_DEBUG permanently?
A: No — leave it off on production. Use it on local/dev/staging. If you must use it on prod, log only (don’t display) and rotate logs.
Q: Does WP_DEBUG show JavaScript errors?
A: No — JS errors appear in the browser console. But SCRIPT_DEBUG loads unminified JS so debugging is easier. Server-side JS-related errors (like Node scripts) are separate.
