How to debug and troubleshoot WordPress issues: Complete guide

WordPress is a very stable CMS and, in most cases, works without a hitch. Due to its versatility, however, in certain cases an issue may pop up.

This can happen for several reasons, which is why troubleshooting and debugging are very important. A plugin or theme update might introduce a conflict, a configuration may change, PHP might run out of memory, or a seemingly unrelated website change may cause something to stop working.

Fortunately, WordPress comes with several debugging tools that can make the task much easier.

This article takes a look at how to troubleshoot WordPress issues before diving into WordPress’ debugging tools and debug log. We’ll then look at some of the most common WordPress issues, including the dreaded “There has been a critical error on this website” message, along with their causes and fixes.

What is WordPress debugging?

As the name implies, debugging is a process in which bugs are identified and removed from code. Most, if not all, developers will find themselves debugging code, a routine practice when running and developing software and websites.

A bug is basically unexpected behavior. This unexpected behavior can manifest itself in various ways, including errors, exceptions, warnings, or a function or feature simply not working as expected.

Even if code passes Quality Assurance checks, new bugs may surface after the software has been installed.

This can happen for a variety of reasons, including software being installed in an environment that the developer did not test. In most cases, it is impossible for software developers and testers to test their code in every possible environment.

This is particularly relevant to WordPress. WordPress core, your theme, plugins, PHP, the database, web server, custom code, and other components all need to work together. A WordPress issue does not necessarily mean there is something fundamentally wrong with the software. More often than not, it may be a configuration or compatibility issue.

Fortunately, WordPress comes with a debugging tool straight out of the box called WP_DEBUG. Before enabling it, however, there are a few troubleshooting steps worth taking first.

Troubleshooting WordPress: start with what changed

When a website goes down or an important feature stops working, it can be tempting to start changing things immediately.

In most cases, you’ll get to the bottom of the problem faster by first gathering some basic information.

Back up your website first

Before making changes, make sure you have a recent backup of your WordPress website.

Ideally, troubleshooting and debugging should take place on a staging or testing environment rather than the live website. This lets you reproduce problems and test fixes without potentially causing additional downtime.

If the issue is serious enough that you may need to restore a backup, consider taking a separate backup of the website while it is displaying the error first. By doing so, you may be able to investigate what went wrong afterwards and put measures in place to prevent it from happening again.

Check what is and isn’t working

Start by determining the scope of the issue.

Can you access the WordPress dashboard at /wp-admin? If you can, troubleshooting will generally be easier because you can inspect settings, deactivate plugins, switch themes, and use WordPress’ built-in tools.

Next, check whether the entire website is affected or only a specific area.

For example:

• Is the entire website down?
• Does the front end work while wp-admin does not?
• Is only one page affected?
• Does the problem occur only during checkout or when submitting a form?
• Is the problem limited to logged-in users?
• Does the website work but appear visually broken?

Knowing what still works can be just as useful as knowing what doesn’t.

Try to replicate the issue

If the issue is intermittent, work out whether you can reproduce it.

Understanding the sequence of events that leads to an error can help you narrow things down considerably.

If, for example, an error only appears when you update a particular plugin or submit a particular form, you already have a much better idea of where to start looking.

It also gives you something concrete to test once you think you have fixed the problem.

Ask: What changed?

This is one of the most useful questions you can ask when troubleshooting WordPress:

What changed immediately before the problem started?

Think about recent:

• Plugin installations or updates
• Theme installations or updates
• WordPress core updates
• PHP changes
• Configuration changes
• Custom development work
• Hosting or server changes
• Website migrations
• File changes

If you have WP Activity Log installed, checking the last logged activities can help you determine where the issue lies.

Plugin installations and updates, theme changes, WordPress settings changes, and user activities are some of the first things worth looking for. For example, if a website was working at 10:00 and stopped working at 10:15, finding that a plugin was updated at 10:07 gives you an obvious place to start.

Rather than deactivating plugins or changing settings at random, an activity log lets you prioritize the changes most likely to have caused the issue. This is particularly useful on websites with several administrators, developers, agency users, or automated processes.

This is also why an activity log is most useful when it is installed before you encounter a problem rather than afterwards.

For file-level changes, Melapress File Monitor can provide another piece of the puzzle. It monitors WordPress website files for additions, modifications, deletions, and permission changes, and can compare WordPress core files against their counterparts in the official WordPress repository.

Together, these tools can help you answer two useful questions:

What changed inside WordPress?

and:

What changed in the website’s files?

If these checks do not make the cause obvious, it’s time to gather more technical information.

Using WordPress debug mode and the WordPress debug log

WordPress comes with several built-in debugging options. The two you’ll use most frequently are:

• WP_DEBUG
• WP_DEBUG_LOG

WP_DEBUG reports PHP errors, warnings, and notices generated while WordPress is running.

WP_DEBUG_LOG saves those messages to a log file, making them easier to review or share with a developer.

It is important to distinguish a WordPress debug log from a WordPress activity log.

The debug log records errors generated by software. An activity log records actions and changes occurring on the website.

Both can be extremely useful when troubleshooting, but they answer different questions:

The activity log can tell you what happened before the problem appeared.

The debug log can help tell you what error the software is generating now.

How to enable WP_DEBUG and WP_DEBUG_LOG

Enabling WordPress debug mode requires access to your site’s files.

You can normally access them through FTP, SFTP, SSH, or your hosting provider’s file manager.

Remember to back up your website before modifying configuration files.

1. Locate wp-config.php

Locate the wp-config.php file, which is normally found in the root directory of your WordPress installation.

Open the file using a text editor or your hosting provider’s file editor.

2. Enable WP_DEBUG

Find the WP_DEBUG setting and set it to true:

define( 'WP_DEBUG', true );

If the setting does not already exist, add it before the line:

/* That's all, stop editing! Happy publishing. */

Enabling WP_DEBUG causes WordPress to report PHP errors, warnings, and notices.

3. Enable WP_DEBUG_LOG

To save these errors to a log, add:

define( 'WP_DEBUG_LOG', true );

By default, WordPress will then write debugging information to /wp-content/debug.log. Bear in mind that, depending on your server configuration, this file may be publicly accessible. On production websites, consider using a custom log location outside the public web root or otherwise restricting access to the file.

WP_DEBUG_LOG requires WP_DEBUG to be enabled.

4. Hide errors from website visitors

You generally do not want debugging messages appearing to visitors on a live website. Error messages can expose technical information about your WordPress environment.

To hide them while continuing to log errors, use:

define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Your configuration can therefore look like this:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Debugging should ideally be carried out on a development or staging environment rather than your live website. You should also avoid leaving debug mode enabled after you have finished troubleshooting.

Reproduce the issue

Once debugging is enabled, head back to your website and reproduce the problem.

If clicking a particular button causes an error, click it again. If opening a specific page triggers the problem, reload that page.

Doing so causes the error to occur again while debugging is active, allowing WordPress to capture the relevant information.

Review debug.log

If you’re using the default log location, navigate to:

/wp-content/debug.log

The file can contain a lot of information, so start with errors corresponding to the time at which you reproduced the issue.

Look for details such as:

• The error type
• The affected file
• The affected plugin or theme
• The PHP function involved
• The line of code where the error occurred

If an error repeatedly references a particular plugin, theme, or file, you now have a much stronger indication of where the problem lies.

Once you’ve identified and resolved the problem, turn debugging back off:

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

Don’t leave an old debug.log sitting around unnecessarily either. Debug logs can contain information about your website and should be handled appropriately.

Other WordPress debugging options

WP_DEBUG and WP_DEBUG_LOG will be enough for many WordPress issues. WordPress does, however, include some additional options that can be useful in specific circumstances.

SCRIPT_DEBUG forces WordPress to use the development versions of its core JavaScript and CSS files rather than the minified versions. This can help when troubleshooting scripts, styles, or plugins and themes that modify them.

define( 'SCRIPT_DEBUG', true );

SAVEQUERIES records database queries, their execution times, and information about what called them.

define( 'SAVEQUERIES', true );

This can be useful for identifying slow database queries or investigating plugin and theme database activity. It does add overhead, however, so it should only be enabled while actively debugging.

There are also debugging plugins available if you need additional information. Query Monitor, for example, provides information about database queries, PHP errors, hooks, HTTP API calls, scripts, and styles, while Health Check & Troubleshooting can help identify plugin and theme conflicts without affecting normal visitors.

Fixing “There has been a critical error on this website”

Getting the “There has been a critical error on this website” alert on your WordPress website is not something that any one of us wants to experience by any stretch of the imagination.

A critical error in WordPress is one that can stop your site from functioning. It is generally the result of a fatal PHP error where WordPress cannot load the resources it needs to continue its normal operations.

There are several reasons why a critical error can occur. Knowing what these reasons are, how to identify the cause, and how to troubleshoot it can help you minimize downtime and get back up and running in the least possible time.

The troubleshooting process is essentially the same one we’ve already covered. Establish what is affected, determine what changed, reproduce the error where possible, and gather information before making changes.

There are, however, a couple of additional things worth checking when you see the WordPress critical error message.

Check your administrator email and Recovery Mode

When WordPress detects certain fatal errors, it can send an email to the site’s administrator address containing information about what went wrong.

The email can also contain a special link that allows you to access WordPress using Recovery Mode.

This is particularly useful when a faulty plugin or theme prevents you from accessing the WordPress dashboard normally. In Recovery Mode, WordPress can pause the problematic component for your administrator session, allowing you to log in and investigate further.

If you don’t receive the email, you can still troubleshoot using FTP/SFTP, your hosting tools, activity logs, and WP_DEBUG.

Check recent changes and the debug log

If you have WP Activity Log installed, look at the activities immediately before the critical error began.

Pay particular attention to:

• Plugin installations and updates
• Plugin activations or deactivations
• Theme changes
• WordPress updates
• Configuration changes

One caveat is that if wp-admin is completely inaccessible, you may not be able to access the activity log from WordPress itself.

For larger or more critical websites, storing activity logs in an external database or mirroring them to another system can make the log available independently of the affected WordPress installation.

Next, enable WP_DEBUG and WP_DEBUG_LOG, reproduce the error, and inspect the resulting log.

The activity log tells you what changed; the debug log can tell you what subsequently failed.

Common causes of WordPress critical errors

Once you’ve gathered some evidence, work through the most likely causes rather than changing unrelated parts of the website.

Plugin and theme conflicts

Plugin conflicts are among the most common causes of serious WordPress errors.

If you recently installed or updated a plugin or theme, disabling or rolling back that change should be one of your first ports of call. If you do roll back, check that the previous version does not contain a known security vulnerability and treat the rollback as a troubleshooting measure rather than a permanent fix.

If you have access to the WordPress dashboard, deactivate the suspected component and test the website.

If you don’t know which plugin is responsible, plugins can be deactivated and re-enabled individually while you continue testing.

If you cannot access wp-admin, plugins can also be manually disabled using FTP/SFTP or your hosting file manager by renaming their folders inside:

/wp-content/plugins/

Themes can be tested in much the same way by temporarily switching to a default WordPress theme.

Use your activity log and debug log first where possible. If both point toward a plugin that was updated immediately before the error appeared, there is little reason to start disabling unrelated plugins at random.

Corrupted WordPress files

Server issues, incomplete updates, malware, and other problems can result in damaged or modified WordPress files.

Check your WordPress files’ integrity and restore known-good copies where required.

Melapress File Monitor can help identify unexpected file changes, including modified or missing WordPress core files. If you need to reinstall WordPress core files, take a full backup of the website and database before doing so.

PHP memory and compatibility issues

WordPress relies on PHP memory to run. Resource-intensive plugins, large workloads, or an insufficient server memory allocation can result in fatal errors when the available memory is exhausted.

The debug or PHP error log will normally make a memory-exhaustion problem relatively easy to identify.

Before simply increasing the limit, check whether a particular plugin, theme, or process is consuming more memory than it should.

PHP compatibility can also cause critical errors. WordPress, themes, and plugins are built on PHP, and newer software may use functions that are unavailable in older PHP versions. Conversely, upgrading PHP without checking compatibility can expose problems in older plugins, themes, or custom code.

If you have recently changed PHP or updated WordPress software, check the requirements of all affected components before making further changes.

Malware or unauthorized file changes

Malware can modify WordPress files and configuration in ways that result in errors or make the website completely inaccessible.

If you have reason to believe malware is involved, treat the problem as a security incident rather than simply fixing the visible PHP error.

Identify unexpected changes, scan the website, restore or clean affected files, and determine how the compromise occurred before returning the website to normal operation.

Other common WordPress issues

Not every WordPress problem produces a critical-error message. Here are some of the other common issues WordPress administrators may encounter and where to start troubleshooting them.

White Screen of Death

The White Screen of Death, also known by its acronym WSOD, manifests itself as a completely blank white screen.

While many factors can contribute to a WSOD, a common culprit is compatibility issues with plugins and themes.

Start by looking at what changed immediately before the problem appeared, then enable the WordPress debug log.

The log can give you better insight into which plugin, theme, file, or line of code is causing the issue. If you determine that a plugin or theme is the culprit, contact the developer for a fix.

Error establishing a database connection

WordPress database connection issues can happen for a variety of reasons. One of the more common symptoms is seeing an “Error establishing a database connection” message.

WordPress relies on its database to store and read data such as settings, users, and posts. Without a connection to the database, the website cannot function.

Check that the database server is up and running and that WordPress can connect to it. Verify the hostname, database name, username, and password configured in wp-config.php, and make sure the database user has sufficient permissions.

If the configuration appears correct, check with your hosting provider for database or infrastructure problems.

PHP memory exhausted

When the memory limit is reached, you will typically see a fatal error stating that the allowed memory size has been exhausted.

Before increasing the limit, make sure nothing is consuming more memory than it should.

Check the debug and PHP logs to identify what was running when the limit was reached. If your WordPress website has simply grown too large for the resources available, speak with your hosting provider about increasing the limit or upgrading your hosting plan.

Parse error or syntax error

A parse or syntax error happens when PHP tries to execute code but encounters invalid syntax.

The error itself will usually identify the affected file and line number, making this one of the easier errors to start investigating.

If you recently added custom code, undo the change. If the error references a plugin or theme, disable it and check whether an update or fix is available.

Also check compatibility with your current PHP version.

Maximum execution time exceeded

A Maximum execution time exceeded error occurs when an action takes longer than the server allows it to run.

First, identify which action caused it.

Look at the last thing you did on the website and, if you have a WordPress activity log, refer to it. Check scheduled tasks or cron jobs that might be stuck, then enable WP_DEBUG and reproduce the issue.

If the log points to a plugin or theme, investigate why that process is taking so long or contact the developer.

Increasing the execution time may be appropriate in some cases, but it is better to establish why the process exceeded the limit first.

Internal Server Error / Error 500

An internal server error, also known as Error 500, is not specific to WordPress. It is an HTTP response returned when the web server encounters a problem but cannot provide a more specific error.

This catch-all nature can make it difficult to troubleshoot.

Your PHP and web-server logs are particularly useful here.

Other things to check include:

• Recently installed or updated plugins
• Theme changes
• .htaccess on Apache
• PHP memory
• WordPress core files

Rather than changing all of these at once, start with whatever changed immediately before the error appeared.

Failed updates and maintenance mode

Updates are one of the most important aspects of good WordPress governance. They provide bug and security fixes and can add new functionality.

An update may fail for several reasons, including connectivity problems, file permissions, resource limits, or plugin conflicts.

If an update fails, trying again may be worthwhile if the failure was caused by a temporary connection problem. If it repeatedly fails, check WordPress Site Health, file permissions, available resources, and your error logs.

WordPress may also become stuck in maintenance mode following an update that did not complete.

During WordPress core, plugin, and theme updates, WordPress may temporarily create a .maintenance file in the root directory. If an update breaks, this file may remain in place.

To take WordPress out of maintenance mode, connect using FTP/SFTP or SSH and delete the .maintenance file. You may also need to clear your website cache.

If this happens repeatedly, investigate why the updates are failing rather than simply deleting the file each time.

What to do when you can’t identify the problem

WordPress environments can be wildly different from each other, and obscure errors can happen from time to time.

If the issue isn’t listed above, return to the same process:

1. Establish exactly what is broken.
2. Determine when the problem started.
3. Check what changed beforehand.
4. Reproduce the issue.
5. Check your activity and file-change logs.
6. Enable WordPress debugging.
7. Review PHP and server logs.
8. Isolate likely plugins, themes, or other components.
9. Test your fix.

A staging or testing environment can be of great help here. It gives you somewhere to troubleshoot issues, disable components, and reproduce errors without risking your live website.

Sometimes, however, the best next step is to involve your hosting provider, plugin vendor, or a WordPress developer.

The more useful information you can provide them, the easier it will generally be for them to investigate.

Try to include:

• A description of the problem
• When it started
• How to reproduce it
• Relevant debug-log entries
• Recent WordPress changes
• Recent plugin or theme updates
• The affected URLs or functionality
• Your WordPress and PHP versions

If the developer needs access to your WordPress website, avoid sharing your own administrator username and password.

Melapress Login Security allows you to create temporary WordPress logins for developers, freelancers, and other third parties. You can assign the appropriate role and configure the login to expire after a defined period, at a specific date and time, or after a maximum number of logins.

If you’re also using WP Activity Log, you’ll have a record of the activity carried out through that account while the developer troubleshoots the website.

Once they’re finished, the temporary access can expire instead of leaving another permanent account behind.

Troubleshooting WordPress issues without the guesswork

Troubleshooting is a good skill to have and can help you in countless ways. Not only will you be able to minimize downtime, but understanding what happened can help prevent the same issue from occurring again.

WordPress provides useful debugging functionality through WP_DEBUG, WP_DEBUG_LOG, and its other debugging options. These tools can help identify errors in plugins, themes, custom code, database queries, and other parts of your website.

However, technical errors are only one side of troubleshooting.

An activity log can show you what changed immediately before a problem appeared, while file monitoring can help identify modifications to the files underneath WordPress.

The important thing is to avoid troubleshooting blind.

Establish what broke, determine what changed, reproduce the problem where possible, and use the information available to work through the possible causes methodically.

More often than not, doing so will get you much closer to the source of the problem – and get your WordPress website back up and running with considerably less trial and error.

FAQs