You're troubleshooting a WordPress problem, but all you see is a white screen or a generic error message. No details. No clues.

WordPress is hiding the real error from you—on purpose.

Debug mode tells WordPress to stop hiding and start showing you what's actually going wrong.

Why Errors Are Hidden by Default

WordPress hides error messages from visitors for good reasons:

  • Security: Error messages can reveal file paths, plugin names, and other information that attackers could use
  • Professionalism: Visitors don't want to see PHP warnings on your homepage
  • Functionality: Many sites run with minor warnings that don't actually break anything

But when you're troubleshooting, you need to see those errors. That's what debug mode is for.

Enabling Debug Mode

Open your wp-config.php file (in your WordPress root directory) and find this line:

define('WP_DEBUG', false);

Change it to:

define('WP_DEBUG', true);

Save the file and reload your site. Errors will now display on screen.

Additional Debug Options

For more control, you can add these lines:

// Enable debug mode
define('WP_DEBUG', true);

// Log errors to a file instead of displaying them
define('WP_DEBUG_LOG', true);

// Don't display errors on screen (use with WP_DEBUG_LOG)
define('WP_DEBUG_DISPLAY', false);

With WP_DEBUG_LOG enabled, errors are saved to /wp-content/debug.log. This is useful when:

  • You don't want visitors seeing errors
  • The error happens during a process you can't see (like a cron job)
  • You want to keep a record of errors

What You'll See

Once debug mode is enabled, you might see:

Fatal Errors

Fatal error: Uncaught Error: Call to undefined function some_function()
in /path/to/wp-content/plugins/plugin-name/file.php on line 123

This tells you exactly what's wrong and where. In this example:

  • The error type: Fatal error
  • What happened: Call to undefined function
  • Which file: plugin-name/file.php
  • Which line: 123

Warnings

Warning: Undefined variable $something in /path/to/theme/template.php on line 45

Warnings usually don't break your site completely, but indicate something isn't quite right.

Notices

Notice: Trying to access array offset on value of type null in /path/to/file.php on line 67

Notices are minor issues that might or might not cause problems.

What to Do With the Error

Once you can see the actual error:

  1. Identify the file: Is it a plugin? A theme? WordPress core?
  2. Research the error: Search for the specific error message
  3. Take action:
    • If it's a plugin: Deactivate it, check for updates, or contact the developer
    • If it's a theme: Check for updates or switch themes
    • If it's core: You probably have a compatibility issue with a plugin or theme

The error message almost always points directly to the problem. Once you know which file is failing, you know what needs to be fixed.

Don't Use Debug Mode in Production

Important: Turn debug mode off when you're done troubleshooting.

define('WP_DEBUG', false);

Why?

  • Security risk: Error messages reveal information that attackers can use
  • Bad user experience: Visitors seeing PHP errors looks unprofessional
  • Performance: Debug mode uses additional server resources

Debug mode is a diagnostic tool, not a permanent setting.

Alternative for Ongoing Logging

If you want to monitor for errors long-term without displaying them:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

This logs errors to debug.log without showing them to visitors. Just remember to check and clear that log periodically—it can grow large.

When Debug Mode Doesn't Help

Debug mode shows PHP errors. It won't help with:

  • Server configuration issues: 500 errors caused by .htaccess or server settings
  • Database problems: Connection issues or corrupted tables
  • JavaScript errors: Client-side issues (use browser developer tools instead)
  • Caching issues: Problems caused by stale cached content

For these, you'll need other diagnostic approaches.

What We Do

We typically use server-level error logs rather than WordPress debug mode. Our hosting infrastructure automatically captures all PHP errors, giving us immediate insight without modifying wp-config.php.

That said, we sometimes set up WordPress debug logging for specific scenarios—particularly to track down issues that occur only under certain conditions or during WordPress-specific processes.

For site owners without server log access, debug mode is the fastest way to get from "something's broken" to "here's what's actually failing."

Sharing Errors With Support

If you've enabled debug mode and captured an error but don't know what to do with it, that error message is valuable information for whoever helps you.

Copy the full error message—including the file path and line number—and share it with:

  • Your hosting provider's support team
  • Your WordPress developer
  • A support forum or community

The error message transforms your support request from "my site is broken" to "here's exactly what's failing"—which leads to much faster resolution.

Need help interpreting an error? Contact our support team—we can quickly diagnose what the error means and how to fix it.

This article is part of our WordPress Troubleshooting guide—a complete resource for diagnosing and fixing common WordPress errors.