The Ultimate Guide to WordPress Debug Mode

Anna Fitzgerald
Anna Fitzgerald



Sometimes things don’t work as intended. This is especially true for software — the more complex and sophisticated the code you’re using to power your WordPress website or host your content, the greater the chance that something will go wrong.

Site owners learning how to debug WordPress

Consider the popular content management system (CMS) WordPress, now used by more than 35 percent of websites worldwide. Despite continual software updates and a reputation for reliability, even WordPress deployments occasionally encounter issues, especially when site owners opt to customize key functionality or install multiple third-party plugins.

And while most errors generated by code incompatibilities or restricted resource calls are distracting rather than disastrous, certain conditions may cause your entire site to randomly crash or render it inaccessible. Thankfully, there’s a solution: WordPress debug mode. This built-in functionality helps site owners discover what’s going wrong, why it’s happening and how it can be resolved.

Grow Your Business With HubSpot's Tools for WordPress Websites

In our guide to WordPress Debug Mode we’ll explore what this function does, why it matters, how it works — and answer some of the top WordPress debugging questions.

Let’s get started.

What Does WordPress Debug Mode Do?

Problems in code are often called “bugs” — they can cause anything from poor performance to display errors to total shutdowns of applications or websites. In some cases, the code itself isn’t to blame; instead, it’s the interaction between two pieces of code across differing pieces of software that creates an undesirable result.

The WordPress CMS has been live and in development for more than 17 years, and thanks to reliable and robust update cycles offers a host of content, site and SEO functionality that is easy-to-use and largely error-free. As websites become more complex and content-rich, however, the services and solutions used to manage these assets at scale can cause website conflicts.

WordPress debug mode offers a way to identify these errors as they occur and help identify the underlying source of software issues. As noted by the official WordPress support website, debugging tools in WordPress can help programmers “be more productive in your coding as well as increasing the overall quality and interoperativity of your code,” while non-programmers can use debugging tools to relay specific error information to technology troubleshooting teams.

How Do I Debug WordPress?

WordPress is coded using hypertext processor (PHP), an open-source, general-purpose scripting language that provides significant flexibility and agility for developers. WordPress code also contains a built-in debugging mode located in the wp-config.php file, but is typically turned off by default, and looks like this in the config file:

 define( 'WP_DEBUG', false );

To activate WordPress debug mode, simply change the config text string to this:

 define( 'WP_DEBUG', true );

This will cause all PHP errors, notices and warnings to be visually displayed on your website. In some cases, the errors identified may seem benign or trivial, which may indicate that they don’t follow PHP data-handling conventions or other rules. Remediating these issues isn’t necessary but can help reduce total code size and improve website functionality.

In other cases, PHP errors may be related to code conflicts or outdated functions that are hampering website performance and may eventually cause your site to crash.

Your Top WordPress Debug Questions Answered

Below we'll answer some commonly asked questions.

1. What’s the best way to enable WordPress debugging?

There are three options to activate WordPress debugging mode:

Enable it directly from WordPress PHP code

As noted above, this requires modifying the wp-config.php file to activate debugging mode and display errors. While it’s not a complicated change, it’s not recommended if you’re not comfortable with PHP programming and WordPress PHP code specifically.

Use your hosting provider

Many hosting providers allow site owners to activate WordPress debugging mode directly from website admin consoles within the hosting platform itself. While the format varies from provider to provider, it’s worth checking here first before modifying PHP code directly.

Leverage a third-party plugin

Plugins are one reason for the massive success of WordPress — rather than take on the task of adding every function directly, WordPress developers have made it possible for developers to create plugins that perform specific actions when tied into CMS deployments, so long as these plugins meet WordPress code guidelines. Plugins offer the easiest way to activate WordPress debug mode and often come with additional features to help track and monitor errors.

Worth noting? No matter how you activate WordPress debugging mode, it’s best used on sites that are in-development or deployed on testing servers. If you’re currently building a WordPress site or developing a new WordPress plugin, for example, it’s worth using debug mode to identify and remediate potential errors before going live.

And when you’re doing debugging — either to fix specific errors or evaluate site performance — always remember to turn WordPress debugging mode off again.

2. Should I use the WordPress debug log?

While activating WordPress debug mode will display code errors, it won’t save these errors for future reference. Activating the WordPress debug log allows any errors to be saved in the wp-content/debug.log found in your site’s file system. To activate the debug log, this code must be present in the wp-config.php file:

 define( 'WP_DEBUG_LOG', true )

3. What WordPress debug plugins are available?

There are a host of WordPress plugins to help manage debugging mode.Two of the most popular are Query Monitor and Debug Bar; both allow you to easily activate the debugging mode in WordPress but also offer additional features.

In the case of Query Monitor, debugging capabilities are extended to include Ajax calls, REST APIs calls and user capability checks. Debug Bar, meanwhile, adds a debugging menu to the WordPress admin bar that displays query, cache and additional debugging information at-a-glance to streamline the process.

4. Are there any risks to debugging WordPress?

While activating WordPress debug mode allows site owners to track down specific issues and test new deployments for compatibility before live release, debugging does introduce potential risks.

The most worrisome are security concerns; if debugging mode is activated on live sites, malicious actors can gain access to underlying code operations. If they can then compromise administrative environments they may be able to insert new code which allows them to exfiltrate site data or install digital “backdoors” that enable long-term access.

Why Debugging WordPress Matters

WordPress sites are designed for streamlined operation and simple modification using approved third-party plugins and tools. But things don’t always go as planned — if you’re building your own plugin or designing a WordPress website from the ground up you may encounter code conflicts that could negatively impact performance or even cripple sites at scale.

WordPress debugging mode makes it possible to identify these issues before your site or service goes live, in turn reducing the time and effort required to find and fix potential problems.

Use HubSpot tools on your WordPress website and connect the two platforms  without dealing with code. Click here to learn more.

Related Articles

Capture, organize, and engage web visitors with free forms, live chat, CRM, analytics, and more.