WordPress Troubleshooting: How to Find and Fix the Bug, in the Right Order

Jeffy Susan October 22, 2026 0 comments

Why the order matters

Most WordPress troubleshooting guides are a list of things to try: clear the cache, deactivate plugins, switch themes, increase the memory limit, contact your host. All of those are reasonable. The trouble is the order people try them in, which is usually whatever the first search result said.

Picture someone deactivating all 34 plugins on a live WooCommerce store at 3 p.m. on a Friday. The checkout breaks for real customers, the original bug is still there (it was in the theme), and now there are two problems. That’s how a one-problem afternoon becomes a two-problem weekend, and it’s why this guide is a sequence rather than a list.

A note on this post: the 2024 version was titled “11 WordPress troubleshooting techniques” and then listed twelve. That gives you a fair idea of how carefully it was put together. This is a rewrite from scratch.

The troubleshooting steps

Before you start. You need a fresh backup, wp-admin access or hosting file access (the file manager or SFTP), and ideally a staging copy of the site. If the site makes money, do Steps 5 and 6 on staging, not live.

Step 1: Write down the symptom exactly.
Note the exact error text, the URL where it happens, whether it happens logged in or logged out, which browser, and roughly when it started. “The site is broken” can’t be fixed. “The cart page shows a critical error for logged-out visitors since Tuesday” usually can.

Step 2: Find out what changed.
Ask what was updated, installed, or edited in the last 48 hours: plugins, the theme, WordPress core, PHP version, hosting plan, DNS, or a code snippet someone pasted into functions.php. Check the site admin’s inbox for WordPress auto-update emails, which list what was updated and when. Very often the answer to the whole problem is in this step.

Step 3: Turn on the debug log.
Open wp-config.php in the site root, find the line that sets WP_DEBUG, and replace it with these three lines. They write errors to a log file without showing them to visitors.

 

When this works, nothing visible changes on the site. That’s correct.

Step 4: Reproduce the problem.
Load the page or repeat the action that breaks, once or twice. This writes the error into the log.

Step 5: Read the log.
Open wp-content/debug.log. Read the newest lines at the bottom first. Look for PHP Fatal error or PHP Warning, then look at the file path in that line. A path containing /wp-content/plugins/plugin-name/ points at that plugin, and /wp-content/themes/theme-name/ points at the theme. Note the plugin or theme name, because Step 6 uses it.

Step 6: Isolate the cause.
If you can reach wp-admin, deactivate only the plugin named in the log, then retest. If you can’t reach wp-admin, use the recovery mode link that WordPress emails to the site admin after a fatal error (see the WordPress recovery mode documentation), or rename that plugin’s folder in wp-content/plugins using the file manager. Our post on the white screen after a plugin update walks through the folder rename in detail.

Step 7: If the log names nothing, test with plugins off for your session only.
The Health Check & Troubleshooting plugin has a Troubleshooting Mode that disables all plugins and switches to a default theme for your logged-in user only, until you turn it off or log out. Re-enable plugins one at a time inside that mode until the problem returns. (Its last update was about two years ago, so I’d run it on staging rather than on a live store.)

Step 8: Check the server.
If the problem survives with every plugin off and a default theme on, it isn’t WordPress code. Check the hosting error log, the PHP version in the hosting panel, the PHP memory limit, and the disk space. A full disk breaks uploads, caching, and database writes in ways that look like a dozen different bugs.

Step 9: Turn debugging off again.
Set WP_DEBUG back to false in wp-config.php, then delete wp-content/debug.log. The log can contain file paths and other details that are useful to attackers, and on many servers anyone can download it by URL. The WordPress debugging documentation also recommends against leaving debug tools on in production.

Check. The original symptom from Step 1 is gone, logged in and logged out, and debug.log no longer exists.

Common symptoms and where to look first

Symptom	Most likely cause	Where to look first
The whole site is a white screen.	A plugin or theme threw a PHP fatal error, usually right after an update.	Check the recovery mode email, then the debug log.
The site says “There has been a critical error on this website.”	This is the same fatal error, shown with WordPress’s friendlier message.	Check the recovery mode email, then the debug log.
The site says “Error establishing a database connection.”	The database server is down, or the credentials in wp-config.php are wrong.	Check the hosting panel’s database status before touching any file.
One page or feature broke, and the rest of the site works.	A plugin conflict or a recent edit affects only that template or shortcode.	Read the debug log while loading that page.
Changes don’t show up on the live site.	A caching layer is serving an old copy of the page.	Purge the cache plugin first, then the CDN (content delivery network).
wp-admin is very slow, and the front end is fine.	The cause is usually autoloaded options or a heavy admin plugin.	Check the database for oversized autoloaded options.

 

That last row is a long story of its own, and we wrote it up as a read-only audit case study on a slow WordPress admin.

Using AI to read the log, carefully

This part didn’t exist in 2024, and it’s genuinely useful. Pasting the last 30 or so lines of debug.log into an AI assistant and asking “which plugin is causing this, and what does the error mean?” gets you a plain-English explanation of a stack trace faster than any forum thread will. It’s very good at that.

Two cautions, though. First, read what you paste. A debug log can contain server paths, email addresses, and occasionally a database error that includes a query with customer data in it. Strip those out first. Second, don’t let the assistant’s fix go straight into the live site. A snippet from a chatbot, pasted into functions.php, is one of the easiest ways to cause the exact fatal error this guide started with. A function name that clashes with one the theme already declares is enough to take the site down.

There’s a better pattern for AI on a WordPress site, and it’s read-only. An AI agent that can look at the plugin list, versions, cron jobs, and autoloaded options, but can’t change anything, can do most of Step 2 and part of Step 8 (the PHP version and memory limits) without any risk. That’s why we built Auditra, our read-only WordPress inspection tool, the way we did.

When to stop and call someone

Some problems are a bad idea to fix yourself, however good the guide is. Stop and get help if any of these are true:

• You see files, admin users, or redirects that nobody on your team created, because that points to a compromise rather than a bug.
• The database connection error persists after the host confirms the database server is running.
• The checkout or payment flow is broken on a live store and customers are affected right now.
• Nobody can find a recent backup, so any change you make can’t be undone.
• The debug log is empty, the server logs are empty, and the problem is still there.

Checklist

• Take a fresh backup before changing anything.
• Write the symptom down exactly, including the URL and whether you’re logged in.
• List everything that changed in the last 48 hours.
• Turn on the debug log with display off, reproduce the problem, and read the newest lines.
• Deactivate only the plugin or theme the log names.
• Use per-user troubleshooting on staging when the log names nothing.
• Check the server’s error log, PHP version, memory, and disk space.
• Turn debugging off and delete debug.log when you’re done.

FAQ

That’s the order we follow. If yours is different and it works, I’d honestly like to hear it in the comments.

Addendum: checking your site the 2026 way

Added October 2026. We first wrote this guide in 2024, and the steps above still hold. What’s changed is how much of the looking you can hand to an AI assistant without giving it the keys. Before you start deactivating anything, try one of these two free tools we built. Both are read-only, so neither can change your site.

• Auditra is a WordPress plugin that lets Claude or any MCP-compatible AI assistant inspect your plugins, known vulnerabilities, cron jobs, and autoloaded data, and then explain what it finds in plain English.
• The WordPress Security Audit skill is a Claude skill that checks plugin and theme versions against vulnerability databases, core files, wp-config settings, and signs of malware, which is the right first move when a bug might really be a hack.

Run either one before Step 6 and you’ll usually know which plugin to look at before you touch a single setting.