A blank page does not reveal whether the error is caused by a plugin, the template or PHP. WordPress debug mode helps you identify where to look for the problem, but if configured incorrectly, technical details may be visible to visitors. Therefore, log errors rather than displaying them on the website interface.

It isn’t always clear what needs to be changed in the wp-config.php file, or where the log is located. In this guide, we’ll walk you through, step by step, how to safely configure WP_DEBUG and WP_DEBUG_LOG, how to locate the debug.log file, and how to interpret the entries. We’ll also show you when it’s worth checking your hosting provider’s PHP error log, for example if WordPress won’t even start up. Finally, we’ll go through how to disable debugging and why it’s important to remove the log file from your live site. Debug mode doesn’t fix the error, but it helps you find its source.

What does WordPress debugging in debug mode involve, and when should you use it?

WP_DEBUG is one of WordPress’s PHP constants. When enabled, debugging information becomes available, helping you to understand what is happening whilst the website is running. WordPress debug mode is a useful starting point if, following an error, it is unclear whether WordPress, the theme or one of the plugins is affected.

Treat log entries as clues, not as definitive diagnoses. A filename or line of code may indicate where the problem occurred, but not necessarily what caused it. To interpret the message, consider what action preceded the error, whether an update has taken place, and whether the issue can be reproduced.

The aim of troubleshooting is to systematically identify the source of a fault. The basics of troubleshooting also outline this diagnostic process. This guide focuses on WordPress’s own troubleshooting features. Analysing database connection errors and web server logs is a separate topic. Your hosting provider’s PHP error log can be useful if WordPress has not yet reached the stage where it generates its own log.

What sort of errors can WP_DEBUG help with?

WP_DEBUG can help identify PHP errors, warnings and messages indicating deprecated functions. These may appear following an update, or when using a particular page, form or administrative action. The file path shown in the log may refer to a plugin, a theme or a WordPress file.

• PHP error: may indicate that the execution of the code has been interrupted.
• Warning: this may highlight a section of code that could cause problems later on.
• Message about an obsolete function: this may indicate that a component is using an older programming solution.

The message alone does not prove that the component mentioned caused the error. It is possible that a plugin’s code is malfunctioning due to an error in another component. Make a note of when the message appeared, what action preceded it, and exactly which file it refers to.

What is the difference between debugging and troubleshooting?

WP_DEBUG makes error information visible, but it does not fix the code. Debugging serves to identify the problem. Fixing the problem is a separate step, which involves modifying the relevant code or settings. You should then check whether the change has resolved the error and has not caused any new operational issues.

1. Diagnosis: record the error message and the circumstances under which it appeared.
2. Modification: make changes based on the identified cause, preferably in a test environment.
3. Check: repeat the relevant action and see if the error has been resolved.

Before modifying any files or settings, make a backup so that you can restore the previous state in the event of an error. If a test environment is available, test the changes there rather than directly on the live website used by visitors.

How do you enable WordPress debug mode in the wp-config.php file?

The settings must be specified in the wp-config.php file located in the WordPress root directory. Before making any changes, please back up the file so that you can restore the original version in the event of a typo or incorrect setting.

1. Make a backup. Download your current wp-config.php file or copy it to a secure location.
2. Open the file. In your hosting provider’s file manager, locate the WordPress installation directory. In the cPanel interface, you can open and edit the file using the file manager. When managing your cPanel hosting, ensure that you are working in the correct website directory.
3. Check your existing settings. Look for the names WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY. If any of these are already present, modify their values; do not add any new definitions.
4. Paste the configuration into the file. The lines should be placed before the closing comment in the WordPress editor, which usually contains the text ‘That’s all, stop editing!’. After saving, reload the page and check that it works.

Which WP_DEBUG settings are best used together?

WP_DEBUG enables WordPress debug mode. WP_DEBUG_LOG allows debug messages to be written to a file, whilst WP_DEBUG_DISPLAY controls whether these are displayed on the website. On a live site, disable on-screen display. You can also disable this using the display_errors PHP setting.

define( 'WP_DEBUG', true );

define( 'WP_DEBUG_LOG', true );

define( 'WP_DEBUG_DISPLAY', false );

@ini_set( 'display_errors', 0 );

This configuration logs errors but does not display them to visitors. The Official WordPress Troubleshooting Guide provides further details on how constants work and on logging.

How can you safely edit the wp-config.php file?

Before saving, check the semicolons and quotation marks, and ensure that each define() line sets a separate constant. Do not define the same constant twice, as this may cause a warning or unpredictable behaviour. After making changes, try opening both the website and the WordPress admin panel.

When debugging WordPress (in debug mode), logging is a more secure option than displaying detailed PHP messages directly. If the page displays an error after you have saved the configuration file, revert to the original copy and then check the changes again.

Where can you find the debug.log file, and how do you read the entries?

If you have enabled logging via the WP_DEBUG_LOG setting, WordPress will, by default, create a debug.log file in the wp-content directory of your installation. Open the WordPress root directory in your hosting provider’s file manager, then navigate to the wp-content folder. Locate the file and either download it or open it in text view. If you have a custom log path, look for it in that location.

Before you go through the posts, make a note of when the error occurred and what action you were performing at the time. For example, make a note if, after updating a plugin, a blank page appears when you open that plugin’s page. Then look for log entries close to that time. Entries both before and after the error may provide important context.

Which error message could be the most important clue?

Examine the error type, the path of the affected file and the line number provided. The file name may include an extension or template directory, whilst the line number indicates where in the file the message originated. The time of the error and the file path together help narrow down the investigation. This does not yet prove that the component in question is faulty. A warning or an entry referring to an obsolete function does not necessarily cause the page to crash.

The PHP error logging documentation provides information on how PHP error logging generally works. The WordPress log is not the same as the web server logs. This section focuses on interpreting the debug.log file; a detailed analysis of the server logs is a separate topic.

How can you distinguish between the symptom and the possible underlying cause?

Compare the time of the error with any recent plugin or theme modifications, updates and configuration changes. If the log contains the path to a plugin, note whether the error occurred after it was updated or activated. The component named in the file may be involved, but a log entry on its own does not prove a cause-and-effect relationship.

Test your hypothesis using a controlled test, preferably in a test environment, and make only one change at a time. This will allow you to determine whether the symptom is related to that particular change. When debugging WordPress (in debug mode), compare the log entries with the reproducible behaviour; do not draw definitive conclusions from a single line of code.

How can you investigate the error without revealing any data?

The log may contain useful technical data, paths and details revealing information about the server environment. You should therefore not display PHP messages to visitors on a live website. Set WP_DEBUG_DISPLAY to false and log errors to a file. If a test environment is available, trigger the error there; this way, you are less likely to disrupt visitors’ use of the website.

Follow these steps, and at the end of the test, reset the debugging settings:

1. Make a backup. Before modifying the configuration and the relevant files, save the current state.
2. Enable logging. Configure the system to write errors to a file and disable on-screen display.
3. Reproduce the error. Carry out the action that causes the error to occur and make a note of the time.
4. Check the log. Find the entry closest to the relevant time and note down the message, the file path and the component concerned.
5. Close the investigation. Reset the debugging settings and, after ensuring that the necessary information has been safely saved, delete the log file from the live website.

What should you do if the name of a plugin or theme appears in the log?

Make a note of the component name, the full error message and the circumstances in which the error occurred. Compare these with any recent changes, but do not treat the file name as evidence in itself. If a test environment is available, use it to check whether disabling or updating the specified plugin or theme alters the behaviour. Do not delete or overwrite code based on a single log entry.

How can you protect debugging information?

Keep the on-screen error display switched off even whilst the diagnosis is taking place. Do not copy the contents of the log to a public forum or any platform where anyone can access it. If you need to share an extract, first remove any personal details or information that could identify the environment, such as full paths. After the investigation, check whether you still need the log, and do not allow entries to continue accumulating on the live website.

When disabling WordPress debug mode, check your website and the admin panel, then ensure that debug mode is switched off. For further information on hosting and WordPress settings, the aWh knowledge base is also a useful starting point.

How do you disable debug mode, and when should you check the hosting environment?

When you’ve finished troubleshooting, don’t just check whether the error message has disappeared. Restore the temporary settings, remove the log file from the live website, and then test the affected function again. This ensures that the data used for diagnostics does not remain accessible unnecessarily, and also allows you to check whether the website has returned to normal operation.

1. Open the wp-config.php file. Make a backup of it, then look for the constants added for debugging.
2. Disable debugging. Set the value of WP_DEBUG to false. Also check the settings for WP_DEBUG_LOG and WP_DEBUG_DISPLAY to ensure that logging or on-screen display is not left active.
3. Save the changes, then check the page. Reload the relevant page and the admin interface. Repeat the action that previously caused the error.
4. Remove any logs that are no longer required. Once the diagnosis is complete, delete the debug.log file from the live site so that its contents do not remain there unnecessarily.

What checks should you carry out when closing a bug report?

Check that no PHP errors or technical warnings are displayed on the website. Review the modified configuration again, paying particular attention to the values of constants and any duplicate definitions. Then test the previously faulty function, such as the login process or the loading of the affected page. WP_DEBUG aids diagnosis, but does not in itself guarantee that the error will be resolved.

When are WordPress hosting and the knowledge base relevant?

If you find traces in the log file that are more likely related to the runtime environment, separate your WordPress settings from the hosting environment. In this case, the next step should be to investigate the hosting environment, rather than modifying WordPress files at random. A detailed analysis of server-side logs requires a separate investigation. For aWh’s cPanel hosting plans, the location of the PHP error log and how WordPress writes the log to a location that is not accessible via the web are explained in the knowledge base article on debug mode.

The aWh WordPress Hosting plan comes with WordPress pre-installed, whilst the WordPress Toolkit Deluxe assists with managing WordPress. These are tools to aid operation; they are not automatic error-correction tools. For further guidance on settings, the articles in the knowledge base can provide a practical starting point. Once you have completed the WordPress debugging process (debug mode), please also check that the site is functioning correctly by testing it with actual user scenarios.

Ensure secure operation even after troubleshooting

WordPress debug mode is a useful troubleshooting tool, but only keep it enabled for as long as you need the log entries. Once you’ve switched it off, check that the site is working properly and consider how you can prevent a future update or change from causing unexpected disruption. Consistent testing can help you pinpoint the cause of any further errors more quickly.

The PHP version is also part of the WordPress operating environment. With the choice of PHP versions available in the hosting plans, you can tailor the environment to your website’s requirements. When changing the settings, make a note of the current version and the components affected. This will make it easier later on to compare the configuration that works with the one that causes errors.

It is worth briefly documenting the results of your troubleshooting. Note down which action triggered the error, the circumstances under which it occurred, and which change caused the behaviour to change. This record may later help you to distinguish between the effects of your WordPress settings and those of the hosting environment.

Take a look at aWh’s WordPress hosting solutions and choose the environment that best suits your website’s operational needs. Thorough debugging and secure configuration provide a solid foundation for more reliable WordPress operation.

Frequently asked questions about troubleshooting WordPress

Can WordPress debug mode be enabled from the admin dashboard?

The default WordPress admin interface does not have a built-in toggle for debug mode. This setting typically needs to be configured in the wp-config.php file, provided you have the necessary file access rights. Some plugins may offer their own control panel, but these are separate tools and not part of WordPress’s core functionality. If you are unable to edit the configuration file, please ask your website administrator for help.

Does WP_DEBUG automatically show which plugin is causing the error?

Not necessarily. The extension name mentioned in the error message may indicate that the error occurred there, but it does not prove that the component itself is responsible. It may be, for example, that a plugin is processing incorrect data passed on by another plugin. Make a note of the function concerned and the file shown in the log, then test it in a development environment to see if the symptom changes when the component is disabled.

What do PHP ‘notice’ or ‘deprecated’ messages in the WordPress log mean?

A notice is usually an informative message about how the code works, and does not necessarily cause the page to stop working on its own. An deprecated message warns that the code is using a PHP function or solution that has been marked as obsolete. Find out which file it relates to, then check whether it appears at the same time as an actual error on the website. The warning alone does not mean that the page is malfunctioning.

Can WP_DEBUG mode affect the performance of a WordPress website?

Yes, debugging can affect performance, particularly if a large number of messages are generated and need to be continuously written to a file. Displaying these messages on screen can also impair the visitor experience if technical messages appear on the page. On a live website, therefore, only use debugging for the duration of the necessary investigation, and switch it off once it is no longer required.

Can WordPress debug mode be used for multi-site installations?

Yes, but with multi-site WordPress installations, bear in mind that the wp-config.php file manages the configuration for the entire installation. The WP_DEBUG setting specified within it therefore typically applies to the whole network, not just a single sub-site. When analysing log entries, make a note of which sub-site the error occurred on and what action was being performed. Separate installations have their own configuration files.

Why isn’t the debug.log file being created after enabling WP_DEBUG_LOG?

The file may be missing for several reasons. Check that WP_DEBUG is enabled, then trigger an action that generates a log message. Logging may fail if WordPress is unable to write to the target directory, or if the log path is set to a custom value. If the system crashes before WordPress even starts up, the error will not necessarily be recorded in this file.

Is WordPress debug mode the same as the browser’s developer console?

No. Debugging WordPress primarily provides information about server-side PHP behaviour. Using your browser’s developer console, you can examine JavaScript errors, network requests and how the page is rendered in the browser, amongst other things. For example, if a button isn’t responding, the console may provide a clue; if a PHP process fails whilst the page is loading, the WordPress log may be more useful.

• wordpress
• php
• monitoring
• guides