Operating a WordPress site can expose you to a range of technical challenges. In such instances, activating debug mode can help identify the root causes of the issues.
This article will explain what debug mode is, how to activate it to inspect error logs, and how to interpret the displayed error messages.
What is Debug Mode?
Debug mode is a special execution state used during software development to identify and fix errors. Unlike the standard operation mode, debug mode allows developers to track the execution steps of a program, observe changes in variable values, and provide various insights into the timing and origins of errors. This mode is an essential tool for developers to locate and resolve logical errors, issues with exception handling, memory leaks, and other bugs, ultimately enhancing the stability and reliability of the program.
In WordPress, debug mode enables the detection of PHP errors, warnings, and notices. By default, to ensure security, WordPress keeps the debug mode disabled, making it difficult to accurately diagnose issues. Activating debug mode can help pinpoint the causes when errors occur on your site.
How to Activate Debug Mode
When a critical error occurs on your WordPress site, a message stating "There has been a critical error on this website. Learn more about troubleshooting WordPress" will appear upon accessing the site.
In some cases, you may experience a blank screen without any error message displayed, preventing access to the site.
To resolve site errors, it's crucial to first identify the underlying causes, which starts with checking the error log.
Error logs are essential diagnostic tools that document issues and exceptional situations within software systems. They play a critical role in tracking the system's operational status and identifying root causes when failures occur. Error logs are typically categorized by severity levels such as DEBUG, INFO, WARN, ERROR, and FATAL, which helps developers and system administrators pinpoint the location, occurrence time, and details of the problem.
WordPress allows you to check error messages by enabling debug mode.
Activating Debug Mode in WordPress
To enable debug mode, access your site via FTP/SFTP and modify the wp-config.php file by changing the debug mode (WP_DEBUG) to true. You will need FTP access for this step.
For example, if you're using FileZilla to connect via FTP, navigate to the root folder where WordPress is installed, hover over the wp-config.php file, right-click, and select View/Edit.
Next, locate the following line in the WordPress configuration file.
define('WP_DEBUG', false);Search for WP_DEBUG to find the line above. By default, WP_DEBUG is set to false as shown. Change false to true.
define('WP_DEBUG', true);Once debug mode is enabled, specific error messages will be displayed on your site.
The example displayed above shows a critical error resulting from a duplicate definition of the your_function() function in the child theme's functions.php file. Deleting the problematic function will restore normal site functionality.
If you cannot locate the wp-config.php file, refer to the section titled "Appendix: Locating the wp-config.php File" below.
If You Can Access the Admin Page, Check Error Logs Using the Error Log Monitor Plugin
If you can't access the site but can log into the admin area, you can install the Error Log Monitor plugin to check the PHP error logs from the dashboard.
Generally, when a critical error occurs on the site, access to the admin panel is also often unavailable, making this method somewhat limited.
Understanding Error Logs
There are various error types in PHP:
- Fatal Error: A severe error that halts site functionality entirely.
- Warning: A non-critical error that still requires attention.
While Fatal Errors must be resolved, Warnings are not necessarily urgent.
Fatal Errors can arise from various causes, such as:
- Call to undefined functions: Fatal error: Uncaught Error: Call to undefined function...
- Reference to non-existent classes: Fatal error: Uncaught Error: Class 'ClassName' not found...
- PHP syntax errors: Fatal error: Parse error: syntax error, unexpected '{'...
- Memory limit errors: Fatal error: Allowed memory size of X bytes exhausted...
- Error due to plugin/theme conflicts: Fatal error: Cannot redeclare function/class...
- File permission errors: Fatal error: Uncaught Error: Failed to open required file...
If any of these errors occur, it indicates a serious issue on the site that necessitates locating and rectifying the problem.
PHP syntax errors typically appear due to version incompatibility or incorrect PHP syntax. For instance, syntax errors like the one below might occur on sites hosted on Cloudways:
Parse error: Unmatched '}' in /home/123456.cloudwaysapps.com/abcdefgh/public_html/wp-content/themes/avada-child/single-movie.php on line 139When encountering such errors, first check the code in the file where the error occurs.
<? if(get_field('movie_genre')){ ?>This type of line can cause an error because, when the 'short_open_tag' setting is turned 'off', PHP fails to recognize <? as the beginning of PHP code.
Cloudways has this feature disabled by default; activating the Short Open Tag setting in your server configuration will resolve the issue. Alternatively, you can convert <? to <?php. (Using complete tags like <?php instead of shorthand tags like <? while coding can help to prevent unexpected errors.)
Warnings can typically be ignored, but it's advisable to resolve them when possible. For instance, this site uses a table of contents plugin named Tocer, which generates the following error each time visitors access the site:
PHP Deprecated: Using ${var} in strings is deprecated, use {$var} instead in /home/public_html/public_html/wp-content/plugins/tocer/inc/class-composite.php on line 264This site uses PHP version 8.3, and the Tocer plugin isn't fully compatible with it, resulting in this error. However, the plugin's functionality remains unaffected.
Even though the plugin operates without issues, if such errors occur in bulk, they can exhaust server resources and are thus undesirable. In fact, this can lead to rapid depletion of traffic.
After Resolving Issues
When encountering a critical error in WordPress, your first step should be to activate debug mode to identify the issue, then proceed to resolve it. Prior to attempting any fixes, it is wise to back up your site to safely store it on your PC or cloud storage.
Specific causes for WordPress site issues may include:
- Plugin compatibility issues
- Conflicts between plugins
- Incompatibility of outdated plugins with the latest WordPress version
- Themes-related problems
- Mismatched theme and WordPress versions
- Errors arising from customization changes
- Server and web hosting issues
- Problems with PHP configuration values
- Incorrect server setup
- Database (DB) connection errors
- PHP version issues (outdated PHP version)
- File and permissions issues
- Corrupted .htaccess file
- Improper file/folder permission settings
- Security and update-related problems
- Running an outdated version of WordPress
- Malware infection
- Security vulnerabilities
- User errors
- Incorrect changes to site URL
- Inappropriate plugin/theme installations
- Technical issues
- PHP version compatibility
- Insufficient server resources
- Corrupt core files
To ensure safe use of WordPress, it's crucial to regularly back up your site and keep WordPress core, themes, and plugins updated to their latest versions. Neglecting updates can lead to security issues, including malware infections or hacks.
Once the issues are resolved, remember to turn off debug mode in the wp-config.php file.
define('WP_DEBUG', false);Leaving debug mode enabled could create security risks and might expose non-critical warnings to your visitors.
When Issues Persist
Typically, enabling debug mode allows you to view error logs and determine the underlying issue. This will guide your troubleshooting efforts.
However, as mentioned earlier, it’s possible to encounter a critical error on the site with no error messages displayed, even after activating debug mode. In such cases, pinpointing the issue can be challenging.
If problems persist, rolling back to a previous version of your site is often the simplest solution. If you have a backup, restore the site using that backup.
Hosting services like Cafe24, FastComet, and ChemiCloud offer automatic restore features, making it easy to revert to any previous version.
Be advised, however, that rolling back will erase any changes or additions made since your last backup, so proceed carefully.
Appendix: Locating the wp-config.php File If You Can't Find It
If you're using conventional web hosting, finding the wp-config.php file via FTP/SFTP is relatively straightforward. However, if you’re hosting your WordPress site on servers you create yourself, like AWS or Vultr, discovering the installation path may be challenging for beginners.
If you can access the WordPress admin dashboard, you can check the WordPress Dashboard » Tools » Site Health » Info tab in the Directories and Sizes section to verify the location of the WordPress directory.
If you cannot access the admin area, you may check the directory by logging into SSH and using the following command:
find . -name wp-config.phpTo utilize this method, SSH access permissions are required. Standard web hosting services often do not provide SSH access due to security concerns, but if you are operating on servers from AWS or Vultr, you can access SSH.