WordPress Troubleshooting: The Complete Step-by-Step Guide (2026)

If your site is down right now, stop panicking. Panic causes data loss. Follow this checklist in exact order.

WordPress Troubleshoot Quick-Start Checklist

1. Back up your site (files + database) before any change
   Do not attempt a fix without a safety net. Even a broken site should be backed up.
2. Switch to safe mode or staging
   If you have a staging site, move there. If not, use the Health Check & Troubleshooting plugin to enter “Troubleshooting Mode” (this disables plugins for you only, keeping the site live for visitors).
3. Replicate the problem and capture the exact error message
   “It’s broken” is not a diagnosis. “500 Internal Server Error on the Checkout Page” is a diagnosis. Take a screenshot.
4. Clear browser, page, object, and CDN caches
   90% of “display” issues are just stale cache. Purge everything.
5. Temporarily deactivate all plugins
   If the site comes back, a plugin is the culprit. Reactivate them one by one.
6. Switch to a default theme (Twenty Twenty‑FIVE)
   If plugins aren’t the issue, your theme code might be broken.
7. Enable WP_DEBUG and review PHP/WordPress error logs
   Stop guessing. Let WordPress tell you what is wrong. (Instructions here).
8. Roll back recent updates
   If the site broke after an update, roll back that specific plugin or theme.
9. Refresh permalinks and check .htaccess
   Fixes 404 errors instantly. Go to Settings > Permalinks > Save Changes.
10. Verify URLs
    Check Settings > General. Are the “WordPress Address” and “Site Address” correct?
11. Scan for malware
    If the code looks weird or files have changed randomly, scan with Malcare or PatchStack.
12. Document steps
    Write down what you did. You might need this for the support ticket.

🛑 Stuck? Need it fixed immediately? If you are staring at a critical error and losing money by the minute, don’t guess. I offer ad-hoc emergency repairs to get you back online fast. Get Emergency WordPress Repair

Before You Start: Safety First

Create a full backup and test your restore process

I cannot stress this enough. If you delete a database table hoping to fix a glitch, there is no “Undo” button. Always BACKUP, BACKUP & BACKUP before process anything.

Use Malcare or your host’s backup tool. Save a copy your computer if possible.

Set up a staging copy

Never cowboy code on a live site. Use:

• Hosted Staging: Most managed hosts (Cloudways, Rocket) have a one-click staging push.
• LocalWP: Clone your site to your own laptop.
• InstaWP: Spin up a temporary disposable WordPress site for testing.

Use Health Check & Troubleshooting

This plugin is mandatory for live site debugging. It allows you to view the site as if all plugins are disabled and the theme is default, while your visitors still see the live, broken (or working) site.

Maintenance mode vs. troubleshooting mode

Troubleshooting Mode: The diagnostic state used by the Health Check plugin.

Maintenance Mode: “Under Construction.” Stops visitors from seeing the site. Use this when the site is visibly broken or leaking data.

Troubleshooting Workflow: Diagnose, Isolate, Fix, Prevent

Define the problem and scope

Who is affected? (Admins? Logged-out users? Mobile users?) When did it start? (After an update? After a server migration?)

Identify variables in your stack

A WordPress site is a house of cards. Identify which card is shaking:

1. Hosting/Server: PHP version, Firewall, Database limits.
2. WordPress Core: Is the CMS files intact?
3. Plugins: The usual suspects for conflicts.
4. Theme: Custom functions.php code often breaks things.
5. Cache: Browser, Page (FlyingPress), Object (Redis), CDN (Cloudflare).
6. Local Environment: Is it just your internet connection?

Replicate and eliminate variables

Disable one layer at a time. Disable cache. Then plugins. Then theme. If the error persists with everything off, it’s a Server or Core issue.

Test on a fresh install

If you can’t fix it, install a blank WordPress site on the same server. Does the error happen there? If yes, it’s your host. If no, it’s your specific site configuration.

Fix Common WordPress Errors Fast

There has been a critical error / White Screen of Death (WSOD)

This is a PHP fatal error.

• Fix: Enable WP_DEBUG (see here) to see the actual error message. It will usually point to a specific file (e.g., /wp-content/plugins/bad-plugin/index.php). Rename that folder via FTP to disable it.

Error establishing a database connection

WordPress cannot talk to MySQL.

• Fix: Check wp-config.php. Are the database name, user, and password correct?
• Fix: Check if the database server is down (contact host).

Stuck in maintenance mode

You see “Briefly unavailable for scheduled maintenance.”

• Fix: Log in via FTP. Delete the .maintenance file in the root directory.

⚠️ Found malware or strange files? Deleting the visible file isn’t enough; the backdoor is still there. If your site is redirecting to spam or showing warnings, you need a forensic cleanup. Get Professional Hacked Website Repair

404s and broken permalinks

Pages exist but show “Not Found.”

• Fix: Go to Settings > Permalinks and simply click Save Changes. This regenerates the .htaccess rewrite rules.

Login loop / Locked out

• Fix: Clear browser cookies.
• Fix: Rename the /plugins/ folder via FTP to force-disable all plugins.

WordPress not sending email

• Fix: PHP mail is unreliable. Set up SMTP using a plugin like FluentSMTP.

FluentSMTP – WP SMTP Plugin with Amazon SES, SendGrid, MailGun, Postmark, Google and Any SMTP Provider

Mixed content and SSL warnings

• Fix: Install Better Search Replace. Search for http://yourdomain.com and replace with https://yourdomain.com.

Better Search Replace

Redirect loops (ERR_TOO_MANY_REDIRECTS)

• Fix: Check your SSL settings in Cloudflare. It should be “Full (Strict).” If set to “Flexible,” it causes a loop.

Media upload failures

• Fix: Check file permissions on /wp-content/uploads/. Should be 755.
• Fix: Increase upload_max_filesize in PHP settings.

PHP memory limit / Timeouts

• Fix: Edit wp-config.php. Add: define( 'WP_MEMORY_LIMIT', '256M' );.

Slow site performance

• Fix: Run a Lighthouse audit. Usually large images or too many external scripts.

Cron problems

Fix: Disable default WP-Cron in wp-config.php (define('DISABLE_WP_CRON', true);) and set up a real server cron job to run every 5 minutes.

Resolve Plugin and Theme Conflicts

Use Troubleshooting Mode

Using the Health Check plugin, enable Troubleshooting Mode. Enable plugins one by one until the error reappears. The last one enabled is the killer.

Health Check & Troubleshooting

Manually disable plugins via SFTP

If you can’t access the dashboard:

1. Connect via SFTP/FTP.
2. Navigate to /wp-content/plugins/.
3. Rename the folder of the suspect plugin (e.g., elementor to elementor_OFF).
4. This forces WordPress to deactivate it.

Audit custom code snippets

Check your functions.php or code snippet plugins. One bad line of code (like a missing semicolon) brings down the whole site.

Caching, CDN, and DNS Conflicts

Understand the layers

• Browser: Local to you. Test in Incognito.
• Page Cache: HTML files stored by plugins (FlyingPress). Purge this first.
• Object Cache: Database queries stored in RAM (Redis). Flush this if database data looks old.
• CDN: Stored on Cloudflare’s edge.

Purge/bypass CDN

Put Cloudflare in “Development Mode” to bypass the cache and see real-time changes.

Debugging Tools, Logs, and WP-CLI

Enable WordPress debug constants

Open wp-config.php and add/change these lines to see errors:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false ); // Don't show errors to visitors

The errors will now be saved to a file at /wp-content/debug.log.

WP-CLI Troubleshooting Cheat Sheet

If you have SSH access, wp-cli is the fastest way to fix a site.

• Check status: wp core check-update
• List plugins: wp plugin list
• Disable plugin: wp plugin deactivate plugin-name
• Switch theme: wp theme activate twentytwentyfour
• Flush cache: wp cache flush
• Search/Replace: wp search-replace 'http://old.com' 'https://new.com' --all-tables
• Create admin: wp user create julian julian@example.com --role=administrator
• Verify Checksums: wp core verify-checksums (Checks if core files have been hacked/modified).

Query Monitor

Install this plugin to see slow database queries, PHP errors, and API call failures in real-time on the front end.

Query Monitor – The developer tools panel for WordPress

Server and Hosting Configuration Checks

• File Permissions: Folders should be 755. Files should be 644. wp-config.php should be 600 or 440.
• PHP Version: Ensure you are on 8.1 or 8.2. WordPress 6.x runs best here.
• Resources: Check memory_limit (256M+), max_execution_time (60s+), and max_input_vars (3000+).

Troubleshoot the Block Editor (Gutenberg)

Fix REST API errors

If the editor says “Updating failed,” the REST API is blocked. Check security plugins or firewall rules blocking /wp-json/.

Diagnose JavaScript errors

On the web brower, right-click > Inspect > Console. Red text indicates JS errors. Often caused by a plugin conflict or mixed content.

Prevention: Harden, Monitor, Maintain

• Update Strategy: Never update on a Friday. Always test on staging.
• Security: Use a WAF (Malcare / PatchStack / Cloudflare).
• Version Control: Use Git. If you break something, git revert saves your life.

When to Escalate: Get Better Support

When you open a ticket with your host or a developer, do not say “It doesn’t work.” Say this:

1. Access: “Here are temporary admin credentials.”
2. What happened: “I updated Plugin X and the checkout page throws a 500 error.”
3. Steps to reproduce: “Go to product page, add to cart, click checkout.”
4. Logs: “Here is the snippet from the debug.log.”

FAQs

Appendix: Glossary of Common Error Messages

• 500 Internal Server Error: Generic “server is broken” error. Usually PHP fatal error or .htaccess syntax error.
• 502 Bad Gateway: The server (Nginx) got an invalid response from the upstream (PHP). Usually server overload or timeout.
• 503 Service Unavailable: Server is overloaded or in maintenance mode.
• 504 Gateway Timeout: The script took too long to run.
• 403 Forbidden: You don’t have permission. Often a WAF blocking you or bad file permissions.
• White Screen of Death (WSOD): A PHP error where “display_errors” is turned off. Check the logs.
• Error Establishing Database Connection: Credentials are wrong or MySQL server is down.
• ERR_TOO_MANY_REDIRECTS: Infinite loop. Usually SSL configuration or conflicting redirect plugins.

Resources, Links, and Further Reading

This guide provides the workflow. These resources are the official tools and documentation you need to execute it successfully.

1. Internal Resources (For When You Need Expert Hands)

If your troubleshooting hits a wall, or you realize the problem requires server-level expertise, you can escalate the issue directly to our team.

2. Official Documentation & Tools

These are the primary manuals for any professional developer.

• WordPress Official Debugging: The master document on enabling WP_DEBUG and reading logs.
  • Link: WordPress Codex Debugging
• WP-CLI Handbooks: The essential command-line reference for rapid troubleshooting and maintenance.
  • Link: WP-CLI Official Docs
• W3C Standards: Documentation on HTTP status codes (400/500 series) and web standards.
  • Link: W3C HTTP Standards
• Query Monitor Plugin: The best free diagnostic tool for seeing slow database queries and PHP errors in the dashboard.
  • Link:  Query Monitor Plugin

3. Security and Threat Intelligence

When diagnosing malware or vulnerabilities, these are the authoritative sources for data.

• PatchStack Vulnerability Database: The most complete database for known vulnerabilities in plugins and themes.
  • Link: PatchStack vulnerability Database
• CyberSecurity Malaysia (MyCERT): National advisories on localized threats and phishing campaigns.
  • Link: MyCERT Official Advisories
• Google Search Console: The primary tool for monitoring crawl errors, 404s, and security issues reported by Google.
  • Link: Google Search Console Login

The Logic of Prevention: Stop Troubleshooting, Start Thriving

You are now equipped with the complete professional workflow to diagnose and fix nearly any WordPress error. You can handle the White Screen of Death and database connection issues with confidence.

But the real question is this: Should you spend your valuable time debugging PHP logs?

Your time is your most expensive resource. Your business thrives when you focus on strategy, customers, and revenue. It does not thrive when you are chasing a missing semicolon or checking file permissions. Troubleshooting is a necessary evil; maintenance is a logical investment.

The most efficient solution is a system that prevents these errors entirely. Stop operating in Reactive Mode and shift to Proactive Mode.

Your Next Step: Automate Reliability

You know how to fix it. Now, let me manage the risk. Hand off the updates, the backups, and the security scanning, and ensure your site is running faster and more reliably tomorrow than it is today.

View WordPress Maintenance & Support Plans.