How to Enable WordPress Debug Mode: A Complete Guide

Knowing how to enable WordPress debug mode is one of the most valuable skills any WordPress site owner or developer can have. When your site throws a blank screen, displays a cryptic error, or behaves unexpectedly, debug mode is the flashlight that illuminates exactly what is going wrong under the hood. This guide walks you through every method, option, and best practice so you can diagnose problems with confidence.

What Is WordPress Debug Mode and Why Does It Matter?

WordPress debug mode is a built-in diagnostic feature that instructs PHP and WordPress to surface errors, warnings, and notices that are normally hidden from visitors. By default, WordPress suppresses these messages to keep your site looking clean for end users. However, during development or troubleshooting, those hidden messages are exactly what you need to pinpoint a broken plugin, a theme conflict, or a misconfigured database connection.

Without debug mode enabled, you might spend hours guessing at the source of a problem. With it enabled, WordPress tells you the file name, line number, and nature of the issue directly. That turns a frustrating guessing game into a structured, solvable task.

Common Situations Where Debug Mode Helps

• White screen of death (WSOD) with no visible error message
• Plugin or theme activation failures
• REST API endpoints returning unexpected responses
• Slow page loads caused by repeated PHP notices in a loop
• Custom code snippets producing fatal errors

Before You Begin: Important Safety Precautions

Enabling debug mode on a live, public-facing website can expose sensitive server paths and code logic to visitors. Always follow these precautions before turning on any debug constants.

Back Up Your Site First

Before editing wp-config.php, create a full backup of both your database and your files. If you introduce a syntax error while editing the configuration file, your site may go offline. A backup ensures you can restore quickly.

Use a Staging Environment When Possible

The safest place to debug is a staging or local development environment that mirrors your production site. Tools like LocalWP, XAMPP (typically installed at C:\\xampp\\htdocs on Windows), or a hosting-provided staging environment let you experiment freely without risking your live site.

Log Errors to a File Instead of Displaying Them

If you must debug on a live server, always write errors to a log file rather than displaying them on screen. We cover the exact constants for this in the sections below.

How to Enable WordPress Debug Mode via wp-config.php

The primary method to enable WordPress debug mode involves editing the wp-config.php file, which sits in the root directory of your WordPress installation. This file contains core configuration constants that WordPress reads on every page load.

Step-by-Step: Editing wp-config.php via FTP or File Manager

1. Connect to your server using an FTP client such as FileZilla, or open the File Manager inside your hosting control panel (cPanel, Plesk, etc.).
2. Navigate to the root of your WordPress installation — the folder that contains wp-admin, wp-content, and wp-includes.
3. Locate the file named wp-config.php and download a copy as a backup before making any changes.
4. Open the file in a plain-text editor. Do not use a word processor like Microsoft Word, as it can introduce invisible formatting characters.
5. Find the line that reads /* That's all, stop editing! Happy publishing. */. You will insert your debug constants above this line.
6. Add the debug constants you need (see the code example below).
7. Save the file and upload it back to your server, overwriting the original.
8. Reload your website or reproduce the action that was causing the error. Check your browser or the debug log file for output.

The Core Debug Constants Explained

WordPress provides several constants that work together to give you granular control over what is reported and where it goes. Here is the recommended configuration for safe debugging on a live server:

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

// Write errors to a log file instead of displaying on screen
define( 'WP_DEBUG_LOG', true );

// Prevent errors from being printed to the browser (safe for live sites)
define( 'WP_DEBUG_DISPLAY', false );

// Hide PHP error output at the server level as a secondary safeguard
@ini_set( 'display_errors', 0 );

// Enable the Script Debug constant to load unminified JS and CSS
define( 'SCRIPT_DEBUG', true );

// Enable Savequeries to log all database queries (use only temporarily)
define( 'SAVEQUERIES', true );

When WP_DEBUG_LOG is set to true, WordPress writes all errors to a file called debug.log inside the wp-content directory. You can then review this file at your convenience without exposing anything to visitors.

Setting a Custom Log File Path

For extra security, you can store your log file outside the publicly accessible wp-content folder by passing a file path string instead of true:

define( 'WP_DEBUG_LOG', '/home/your_username/private_logs/wp-debug.log' );

Replace /home/your_username/private_logs/wp-debug.log with a path that is above your public web root and writable by the web server user.

How to Enable WordPress Debug Mode Using WP-CLI

If you have command-line access to your server, WP-CLI offers the fastest way to toggle debug constants without manually editing files. This approach is particularly useful for developers managing multiple sites or automating deployments.

Step-by-Step: Enabling Debug Mode with WP-CLI

1. Open your terminal or SSH into your server.
2. Navigate to the root directory of your WordPress installation using the cd command.
3. Run the following WP-CLI commands to set each constant:

# Enable WP_DEBUG
wp config set WP_DEBUG true --raw

# Enable logging to file
wp config set WP_DEBUG_LOG true --raw

# Disable on-screen display
wp config set WP_DEBUG_DISPLAY false --raw

# Verify the constants were written correctly
wp config get WP_DEBUG
wp config get WP_DEBUG_LOG
wp config get WP_DEBUG_DISPLAY

The --raw flag tells WP-CLI to write the value as a PHP boolean rather than a string, which is the correct type for these constants. The final wp config get commands confirm the values were saved as expected.

Disabling Debug Mode When You Are Done

Leaving debug mode enabled permanently is a security risk and a performance drain. Once you have resolved your issue, disable it immediately:

wp config set WP_DEBUG false --raw
wp config set WP_DEBUG_LOG false --raw
wp config set WP_DEBUG_DISPLAY false --raw

Reading and Interpreting the Debug Log

Generating a debug log is only useful if you know how to read what it produces. The debug.log file can grow quickly, especially on busy sites, so understanding its structure helps you focus on what matters.

Anatomy of a Debug Log Entry

Each entry in the debug log follows this general pattern:

[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: Undefined index: post_id in /var/www/html/wp-content/plugins/my-plugin/includes/class-handler.php on line 42

• Timestamp: When the error occurred, which helps correlate it with a specific user action or cron job.
• Error type: PHP distinguishes between Fatal errors (site-breaking), Warnings (potential problems), and Notices (informational). Fatals need immediate attention; Notices can often be addressed later.
• Message: A human-readable description of what went wrong.
• File path and line number: Exactly where in the codebase the error originated, so you can open that file and inspect the logic.

Tools for Viewing the Debug Log

Reading a raw log file in a text editor works, but several WordPress plugins make the experience more comfortable:

• Query Monitor — displays errors, database queries, and hook information in an admin toolbar panel in real time.
• Debug Bar — adds a debug menu to the admin bar with PHP warnings, query data, and cache statistics.
• WP Log Viewer — provides a simple admin interface for browsing and filtering the debug.log file without FTP access.

Advanced Debug Options for Developers

Beyond the core constants, WordPress and its ecosystem offer additional tools for deeper inspection.

SCRIPT_DEBUG for JavaScript and CSS Issues

Setting SCRIPT_DEBUG to true forces WordPress to load the full, unminified versions of its bundled JavaScript and CSS files. This is essential when you are tracing a JavaScript error in the browser console, because minified files compress variable names and remove line breaks, making stack traces nearly unreadable.

SAVEQUERIES for Database Performance

When SAVEQUERIES is enabled, WordPress stores every database query, the function that called it, and how long it took in the global $wpdb->queries array. Combined with Query Monitor, this reveals slow queries and N+1 query problems that degrade site performance. Because storing this data has a non-trivial memory cost, disable it as soon as your investigation is complete.

Xdebug Integration for Local Development

For developers working locally, integrating the Xdebug PHP extension with an IDE like VS Code or PhpStorm provides breakpoint-level debugging. You can pause execution at any line, inspect variable values, and step through code logic — a far more powerful experience than reading a log file. Most local development tools like LocalWP support enabling Xdebug with a single toggle in their interface.

Frequently Asked Questions

Is it safe to enable WordPress debug mode on a live site?

It can be safe if you set WP_DEBUG_DISPLAY to false and WP_DEBUG_LOG to true. This configuration writes errors silently to a log file without exposing them to visitors. However, the safest approach is always to debug on a staging environment first and only enable debug mode on production as a last resort for a brief, monitored period.

Where is the WordPress debug log file located?

By default, WordPress writes the debug log to wp-content/debug.log inside your WordPress root directory. You can change this location by passing a full server file path string to the WP_DEBUG_LOG constant instead of the boolean true. Storing it outside the public web root is strongly recommended for security.

Why is WP_DEBUG not showing any errors even though it is set to true?

There are a few common reasons. First, check that WP_DEBUG_DISPLAY is not explicitly set to false somewhere else in your wp-config.php. Second, your PHP configuration (php.ini) or server-level settings might be suppressing output independently of WordPress. Third, some hosting providers override these settings at the server level — in that case, check your hosting control panel for a PHP error reporting option or contact support.

How do I disable WordPress debug mode when I am finished?

Set WP_DEBUG back to false in wp-config.php, or run wp config set WP_DEBUG false --raw via WP-CLI. Also set WP_DEBUG_LOG and WP_DEBUG_DISPLAY to false. After disabling debug mode, delete or archive the debug.log file, since it may contain server path information that could be useful to a malicious actor if the file were ever publicly accessible.

Enabling and managing WordPress debug mode is a fundamental skill, but it is just one of many technical tasks that can slow you down. WP AI Agent is an AI-powered tool that lets you handle WordPress tasks like enabling debug mode, editing configuration files, managing plugins, and much more — all through a simple natural-language chat interface, no manual file editing required.