How to Enable WordPress Debug Mode Safely

Something is broken on your WordPress site. Maybe the page goes blank. Maybe a plugin stops working after an update. Maybe there’s a vague error message that tells you nothing useful. You’ve searched the internet, tried a few things, and you’re still stuck.

At some point, someone tells you: “Just turn on debug mode.”

That sounds simple enough. But if you’ve never touched a WordPress configuration file before, it can feel like opening the hood of a car when you don’t know what you’re looking at.

This guide walks you through WordPress debug mode in plain English — what it is, how to enable it safely, what to do with what you see, and when it’s better to call in a professional instead of digging deeper yourself.

---

What Is WordPress Debug Mode?

WordPress debug mode is a built-in feature that makes WordPress log and display PHP errors, warnings, and notices that are normally hidden from view.

By default, WordPress runs in “quiet” mode. When something goes wrong under the hood — a plugin throws a PHP error, a theme function fails, a database query breaks — WordPress hides it. Visitors see a blank page or a generic error. You see nothing useful.

Debug mode changes that. It tells WordPress: stop hiding the errors. Show me what’s actually happening.

This is incredibly useful when you’re trying to diagnose why your site is misbehaving. It’s also why you need to handle it carefully — because those same errors, if shown to visitors, can expose technical details about your site’s structure that you don’t want public.

---

When Should You Use Debug Mode?

Enable WordPress debug mode when:

• Your site shows a white screen of death (blank page, no error message)
• A plugin or theme update broke something and you can’t figure out what
• You’re seeing a 500 Internal Server Error with no explanation
• Your developer asked you to collect error logs before they start working
• You want to understand what’s causing slow performance on a specific page

Do not enable debug mode as a permanent setting. It’s a diagnostic tool, not a feature you leave on.

---

Before You Start: Back Up Your Site

This cannot be stressed enough. Before editing any WordPress core files, make a backup.

You’ll be editing wp-config.php — the most important configuration file in your entire WordPress installation. A small typo can take your site offline.

If your hosting control panel has a one-click backup tool (most do — look in cPanel or your host’s dashboard), use it now. If you have a backup plugin like UpdraftPlus already configured, run a manual backup.

Once you have a backup, you’re ready.

---

How to Enable WordPress Debug Mode: Step by Step

Step 1: Access Your wp-config.php File

You’ll find wp-config.php in the root folder of your WordPress installation — the same folder that contains /wp-content/, /wp-admin/, and /wp-includes/.

There are two ways to access it:

Option A: Via your hosting file manager
Log into your hosting control panel (cPanel, Plesk, DirectAdmin, etc.), find the File Manager, navigate to your WordPress root folder, and locate wp-config.php. Right-click and choose Edit.

Option B: Via FTP/SFTP
Use a tool like FileZilla. Connect to your server, navigate to the WordPress root, download a copy of wp-config.php to your computer, edit it in a code editor like VS Code or Notepad++, then re-upload.

Option A is faster. Option B gives you a local backup of the file before you change anything, which is safer.

Step 2: Find the Right Line

Inside wp-config.php, search for this line:

php

define( 'WP_DEBUG', false );

This line already exists in every WordPress installation. You don’t need to add it — just change it.

Step 3: Enable Debug Mode Safely

Replace that single line with these three lines:

php

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Let’s explain what each line does:

WP_DEBUG true — turns debug mode on. WordPress now tracks all PHP errors, warnings, and notices.

WP_DEBUG_LOG true — saves all errors to a log file at /wp-content/debug.log instead of showing them on screen.

WP_DEBUG_DISPLAY false — this is the critical safety setting. It prevents errors from being shown to visitors on your live site. Without this line set to false, errors would appear publicly on your pages.

This combination is the safe way to enable debug mode on a live site. Errors are recorded privately; visitors see nothing unusual.

Step 4: Save and Upload

Save the file. If you edited via FTP, upload it back to your server, overwriting the original.

Step 5: Reproduce the Error

Now visit the page or perform the action that was causing the problem. Go to your admin dashboard, try the thing that was broken, trigger whatever error you were seeing.

WordPress is now silently recording what happens in the background.

Step 6: Read the Debug Log

Navigate to /wp-content/debug.log via your file manager or FTP. Open it.

You’ll see entries like this:

[28-Jun-2026 10:14:22 UTC] PHP Warning: Cannot modify header information - headers already sent by (output started at /wp-content/plugins/some-plugin/functions.php:44) in /wp-includes/pluggable.php on line 1412

Each entry includes:

• The date and time of the error
• The type of error (Warning, Notice, Fatal Error)
• A description of what went wrong
• The file path and line number where it happened

This is the information a developer needs to diagnose your problem.

---

Understanding What You See in the Log

Most site owners aren’t PHP developers, and that’s fine. You don’t need to understand every line in the log — but here’s a quick guide to the most common error types:

PHP Fatal Error — Something completely broke. A required function doesn’t exist, a class couldn’t load, a plugin is calling code that no longer works. These are the errors behind white screens of death.

PHP Warning — Something went wrong but WordPress kept running. Often caused by a plugin passing wrong data to a function, or a file that WordPress expected to find but couldn’t.

PHP Notice — Minor issues. Often deprecated functions or variables that weren’t initialized. Usually not the cause of visible problems, but worth noting.

PHP Deprecated — Code that still works today but will stop working in a future version of PHP. Common after PHP version upgrades.

If you see a pattern — many errors from the same plugin folder, the same theme file, or the same line number — that’s where your problem is.

---

What Not to Do

A few things to avoid when working with debug mode:

Don’t leave WP_DEBUG_DISPLAY set to true on a live site. If you do, PHP errors will appear directly on your pages, visible to every visitor. This can expose your file structure, plugin names, and server paths — information that helps attackers understand your setup.

Don’t leave debug mode enabled permanently. Logging every error creates a growing debug.log file. On a busy site, that file can grow very large. Once you’ve collected what you need, turn debug mode off.

Don’t share your debug log publicly. The file paths in your log reveal information about your server structure. Share it only with your developer or support team.

Don’t try to fix PHP errors yourself unless you know PHP. Editing plugin files or theme files without understanding the code can make things worse. If you’ve found the source of the error, that’s enough — hand it off.

---

How to Disable Debug Mode When You’re Done

Go back to wp-config.php and change the three lines back to:

php

define( 'WP_DEBUG', false );
define( 'WP_DEBUG_LOG', false );
define( 'WP_DEBUG_DISPLAY', false );

Or simply return the file to its original state with just:

php

define( 'WP_DEBUG', false );

Save and re-upload. Debug mode is now off. You can delete the debug.log file from /wp-content/ as well, since it may contain sensitive server information.

---

Alternative: WP_DEBUG via a Plugin

If editing wp-config.php makes you uncomfortable, there are plugins that can do it for you. WP Debugging and Query Monitor are two popular options that allow you to toggle debug mode from your WordPress admin panel without touching any files.

Query Monitor in particular is worth mentioning — it adds a toolbar to your admin area that shows database queries, hooks, errors, and performance data in real time. It’s less raw than the debug log but often easier to interpret for non-developers.

That said, plugins that modify your configuration aren’t always available when your site is completely broken (if you can’t access wp-admin, a plugin can’t help you). Knowing how to edit wp-config.php directly is still a skill worth having.

---

When to Stop and Ask for Help

Debug mode is a diagnostic tool, not a repair tool. It helps you find the source of a problem — it doesn’t fix it.

If you’ve enabled debug mode, found errors in your log, and can identify which plugin or theme is responsible, you’ve done the hard part. From there, the fix might be as simple as updating or deactivating a plugin.

But if you’re looking at a wall of PHP errors and don’t know where to start, or if your site is completely offline and you can’t even access the file manager, that’s when it makes sense to get a professional involved.

Some situations that call for a developer rather than a DIY fix:

• Fatal errors in core WordPress files — this often indicates a corrupted installation or a conflict that goes deeper than a single plugin
• Errors that keep coming back after you deactivate the offending plugin
• Database errors alongside PHP errors — these suggest structural problems
• White screen of death across the entire site, including wp-admin
• Errors that appeared after a WordPress core, PHP, or hosting migration

If any of that sounds familiar, my WordPress bug fixing service is designed exactly for this. You send me the debug log (or I access your site directly), I identify the root cause, and I fix it — no guesswork, no trial and error.

---

Keeping Errors From Coming Back

Fixing the immediate error is step one. Preventing the next one is step two.

Most WordPress errors follow predictable patterns: outdated plugins, theme conflicts after updates, PHP version mismatches, or code left over from a previous developer. A proactive maintenance routine catches these before they become visible problems.

If you’re spending time firefighting errors instead of running your business, it might be worth looking at a WordPress maintenance plan — regular updates, uptime monitoring, security checks, and someone to call when something breaks.

---

Debug Mode and Site Performance

One thing worth knowing: even when debug mode is enabled with WP_DEBUG_DISPLAY false, WordPress is doing slightly more work than usual. It’s tracking errors and writing to a log file on every request.

This has a small but measurable effect on performance. It’s another reason not to leave debug mode on permanently.

If your site’s performance is consistently slow even when nothing is technically broken, that’s a separate issue — and one worth addressing directly. Slow loading speeds affect both user experience and search rankings. A proper speed optimization audit identifies what’s actually causing the slowdown: unoptimized images, render-blocking scripts, poor hosting, or code that’s simply inefficient.

---

A Note on WordPress Itself

Sometimes you go through the whole process — enable debug mode, read the log, find the error, fix the plugin — and the errors keep coming. The site is slow, plugins conflict with each other, updates keep breaking things.

This isn’t unusual. WordPress is a powerful platform with a large ecosystem, but that ecosystem comes with complexity. The more plugins you add, the more moving parts there are, and the more opportunities for something to go wrong.

Some site owners reach a point where they ask: is there a better way?

For certain types of sites — content-heavy sites, performance-critical applications, sites that have outgrown their WordPress setup — migrating to a modern stack like Next.js makes sense. No plugins to conflict, no PHP errors to hunt down, significantly better performance out of the box, and a codebase that’s easier to maintain long-term.

It’s not the right move for everyone. But it’s worth knowing the option exists.

---

Summary

Here’s the short version of everything above:

1. Back up your site before touching any files
2. Open wp-config.php in your WordPress root folder
3. Add or update these three lines:

php

   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   define( 'WP_DEBUG_DISPLAY', false );

4. Reproduce the error, then check /wp-content/debug.log
5. Use the log to identify which plugin, theme, or file is causing the problem
6. Turn debug mode off when you’re done
7. If you’re not sure what to do with what you find, ask a developer

WordPress debug mode isn’t magic. It won’t fix your site by itself. But it gives you — or whoever is helping you — the information needed to actually solve the problem instead of guessing.

If you’d rather skip the file editing and have someone handle the diagnosis and fix directly, I’m available.