Troubleshooting Common WordPress Errors: Complete Tutorial

A step-by-step guide to troubleshooting common WordPress errors, from the critical error and white screen to 500, database and redirect errors.

20 mins read
Troubleshooting Common WordPress Errors Complete Tutorial

A WordPress site rarely breaks for no reason. Something changed: a plugin or theme update, a new plugin, a PHP upgrade on the server, a snippet pasted into functions.php, a migration. The error on your screen is a symptom of that change, and troubleshooting WordPress errors is mostly the work of finding it fast without making things worse.

This guide covers the common WordPress errors that take sites offline most often, from “There has been a critical error on this website” and the white screen of death to the 500 internal server error, error establishing a database connection, stuck maintenance mode, redirect loops, 403 errors and 5xx server errors. You get a table that matches each message to its likely cause, a six-step WordPress troubleshooting workflow that works for almost any error, and the specific fix for each message.

Quick answer: to fix most WordPress errors, back up the site, check the admin inbox for a recovery mode email, clear every cache, turn on the debug log, deactivate plugins by renaming the plugins folder over FTP, switch to a default theme, then check your PHP version and memory limit. Change one thing at a time and reload the site after each step.

Checked against the WordPress Advanced Administration Handbook and the server requirements published on WordPress.org.

Before You Start: Back Up and Find the Last Change

Every fix in this guide touches files or settings, so take a full backup first, files and database, even if the site is down. Most hosts can create one from the control panel in a minute, and a backup made before troubleshooting is the one that saves you if a fix goes wrong.

Then answer one question before you open FTP: what changed right before the error appeared? A plugin or theme update, a new plugin, a PHP version change, an edit to functions.php or wp-config.php, a migration or a new SSL certificate. The last change is the first suspect, and naming it often cuts the whole process down to a single step.

Have these ready before you begin:

  • FTP or SFTP access, or your host’s File Manager. FileZilla is a free FTP client for Windows, macOS and Linux.
  • A plain code editor such as VS Code or Notepad++. Word processors swap straight quotes for curly ones, and one curly quote in a PHP file is enough to crash a site.
  • Your hosting account login, so you can reach error logs, PHP settings, phpMyAdmin and support.
  • A staging copy, if your host offers one. Reproducing the problem there lets you test fixes without visitors watching.

Common WordPress Errors at a Glance: Message, Cause and First Fix

Find the message you are seeing and click it to jump to the full fix. Causes are listed in order of likelihood.

Error you seeMost likely causeFirst thing to try
There has been a critical error on this websitePHP fatal error in a plugin or themeUse the recovery mode link in the admin email, then read debug.log
Blank white page (white screen of death)Plugin or theme fatal error, exhausted PHP memoryEnable the debug log, then deactivate plugins via FTP
500 Internal Server ErrorCorrupted .htaccess, plugin error, PHP limitsRename .htaccess, then resave permalinks
Error establishing a database connectionWrong credentials in wp-config.php, database server downCheck DB_NAME, DB_USER, DB_PASSWORD and DB_HOST, then ask your host
Briefly unavailable for scheduled maintenanceAn interrupted update left a .maintenance file behindDelete .maintenance from the site root
Too many redirects (ERR_TOO_MANY_REDIRECTS)Mismatched site URLs, HTTPS or CDN SSL settingsCompare WordPress Address and Site Address, then check your CDN SSL mode
404 Not Found on posts and pagesBroken rewrite rules or moved contentSettings > Permalinks > Save Changes
403 ForbiddenWrong file permissions, an .htaccess rule or a security blockReset permissions to 755 for folders and 644 for files
502, 503 or 504 errorsOverloaded server, exhausted PHP workers, timeoutsWait a few minutes, then contact your host with the exact time
Allowed memory size exhaustedPHP memory limit too low for a plugin or taskRaise WP_MEMORY_LIMIT or ask your host to raise the PHP limit
Parse error: syntax error, unexpected…A typo in code that was just added or editedUndo the edit over FTP, using the file and line in the message
HTTP error when uploading imagesVery large image, low PHP memory, folder permissionsResize the image, then check memory and uploads folder permissions
Your changes do not show upPage, plugin, server or CDN cachePurge every cache layer and test in a private window

How to Troubleshoot WordPress Errors: A 6-Step Workflow

When the message is vague, or the quick fix in the table did not work, run these WordPress troubleshooting steps in order. They move from the least invasive to the most, and each one either fixes the problem or tells you where it lives.

Step 1: Check the Admin Email for a Recovery Mode Link

Since version 5.2, WordPress catches most fatal PHP errors instead of failing silently. Visitors see the critical error message, and WordPress emails the site’s administration address with the name of the plugin or theme that crashed and a special recovery mode login link.

That link opens wp-admin with the faulty plugin or theme paused, so you can deactivate it, roll it back or replace it without touching FTP. Check the spam folder too. If the email never arrives, your server may not be able to send mail, which is common on budget hosting, so continue with the next steps.

Step 2: Clear Every Cache Layer

A surprising number of “errors” are old copies of a page. If you fixed something and still see the problem, or the site looks broken for you but fine for others, a cache is serving a stored version.

WordPress sites often stack several caches: a caching plugin such as WP Rocket, the server cache many hosts run by default, a CDN such as Cloudflare and your own browser. Purge them in that order, then test in a private browser window. Clear the cache again after every fix, or you may decide a fix failed when it actually worked.

Step 3: Turn On the WordPress Debug Log

The debug log turns a vague symptom into a sentence that names the file, the line and usually the plugin or theme responsible. It is the fastest step on this list, so do it before you start switching things off.

Open wp-config.php in your site’s root folder (usually public_html) with your host’s File Manager or an FTP client. Find the line define( 'WP_DEBUG', false ); and replace it with the block below. If there is no WP_DEBUG line, paste the block above the comment that reads “That’s all, stop editing!”. Code added below that comment loads too late to work, and adding a second WP_DEBUG line instead of replacing the first one leaves debugging switched off.

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

Reload the broken page to reproduce the error. WordPress writes it to wp-content/debug.log, with the newest entries at the bottom. Look for “PHP Fatal error” and read the path: the folder name after /plugins/ or /themes/ is usually your culprit. Our WordPress debug mode guide explains how to read each part of a log entry, keep the log private and switch debugging off afterwards. Do switch it off, because on many servers anyone can open debug.log in a browser.

Step 4: Deactivate All Plugins via FTP

Plugin conflicts and broken plugin updates are behind a large share of WordPress errors. If you can reach the dashboard, deactivate plugins from Plugins > Installed Plugins. If you are locked out, do it over FTP.

Open your FTP client, log in with the credentials from your hosting account and go to public_html > wp-content. You will see the plugins, themes and uploads folders.

Contents of the wp-content folder, where the plugins and themes folders are stored

Right-click the plugins folder, choose Rename and call it something obvious, such as plugins-off. WordPress can no longer find any plugin files, so it stops loading all of them. Your content and plugin settings stay safe in the database.

Renaming the plugins folder over FTP to deactivate every WordPress plugin at once

Reload the site. If the error is still there, plugins are not the cause: rename the folder back to plugins and move on to Step 5. If the error is gone, a plugin caused it. Rename the folder back to plugins, then find the culprit by renaming individual plugin folders inside it. Rather than testing them one by one, rename half of them and reload. If the error disappears, the culprit is in the half you renamed; if it stays, it is in the other half. Keep halving the suspect group until one plugin is left. On a site with 30 plugins, that takes about five checks instead of 30.

If you visited the Plugins screen while the folder was renamed, WordPress marks every plugin as deactivated. In that case, rename the folder back and reactivate plugins one at a time from Plugins > Installed Plugins, reloading the site after each one. With SSH access, the whole test takes one command: wp plugin deactivate --all.

No FTP access? You can also deactivate every plugin from phpMyAdmin in your hosting panel by clearing the active_plugins value in the options table. Our guide on how to deactivate plugins when you cannot access wp-admin shows both the FTP and the phpMyAdmin method step by step.

Two places are not covered by the plugins folder. Must-use plugins in wp-content/mu-plugins load automatically, and drop-in files such as advanced-cache.php and object-cache.php sit directly inside wp-content. Caching drop-ins left behind after a migration are a classic cause of errors that survive plugin deactivation, so check them before you blame the theme.

Once you know which plugin is responsible, check its changelog and support forum, roll back to the previous version or replace it. Our guide on how to fix WordPress plugin conflicts covers rollbacks, Troubleshooting Mode and what to send the developer.

Step 5: Switch to a Default Theme via FTP

If plugins are not the cause, test the theme. Only your active theme loads (plus its parent, if the active theme is a child theme), so renaming inactive themes changes nothing. Go straight to the active one.

Inside wp-content, open the themes folder. First make sure at least one default Twenty-series theme, such as Twenty Twenty-Five, is installed there. If none is, download one from WordPress.org and upload it, because WordPress needs a theme to fall back to. Then rename your active theme’s folder, log in to the dashboard and open Appearance > Themes. WordPress shows a notice that the active theme is broken and switches to the default theme.

The themes folder inside wp-content, where the active theme folder is renamed to deactivate it

Reload the site. If the error disappears, the theme is the source. Check for a theme update, ask the developer for a fix or restore the previous version of the theme from your backup. If you use a child theme, test the parent and the child separately, because custom code in the child theme’s functions.php is a frequent culprit. Over SSH, wp theme activate twentytwentyfive makes the same switch.

Step 6: Check PHP Version, Memory and Core Files

When plugins and the theme are cleared, the cause usually sits one level down, on the server.

  • PHP version. If errors started right after your host upgraded PHP, an older plugin or theme may not support the new version. You can switch back in your hosting panel while you update or replace it, but treat that as temporary: WordPress.org recommends PHP 8.3 or greater.
  • Memory limit. “Allowed memory size exhausted” means PHP ran out of memory. Add the line below to wp-config.php, above the “stop editing” comment. If your host caps memory lower than that, only the host can raise it.
  • Corrupted core files. A failed update can leave WordPress files half written. Re-upload fresh copies of the wp-admin and wp-includes folders from WordPress.org, never wp-content, or run wp core verify-checksums over SSH to list modified core files.
  • Server error logs. Some errors happen before WordPress loads and never reach debug.log. Your hosting panel’s error log, or your host’s support team, can see them.
define( 'WP_MEMORY_LIMIT', '256M' );

How to Fix the Most Common WordPress Errors

The fixes below cover the messages site owners run into most often. For rarer PHP and database messages, the Common WordPress errors page in the WordPress Advanced Administration Handbook is the official reference and worth bookmarking.

“There Has Been a Critical Error on This Website”

This WordPress critical error message means a PHP fatal error stopped the site. It has replaced the old blank screen in most cases, and it comes with help: WordPress emails the administrator a description of the error and a recovery mode link (Step 1). If no email arrives, enable the debug log (Step 3), reload the page and read the newest fatal error. Then deactivate the plugin or theme it names. The usual triggers are a plugin update, an incompatible PHP version, a low memory limit and a snippet with a typo.

The White Screen of Death

A blank page with no message is the older face of the same problem: a fatal error WordPress could not catch or display, most often a failing plugin or theme or exhausted PHP memory. Where it appears tells you where to look. If only the front end is white but wp-admin works, suspect the theme. If both are white, suspect a plugin. If only one long post or page is blank, a memory or execution time limit is the likely cause. Work through Steps 3 to 6, starting with the debug log.

500 Internal Server Error

The server knows something failed but will not say what. On Apache and LiteSpeed servers, the first suspect is a corrupted .htaccess file. Over FTP, rename .htaccess in the site root to .htaccess-old and reload the site. If it loads, go to Settings > Permalinks and click Save Changes, which writes a clean .htaccess file. Nginx servers do not use .htaccess, so skip straight to the next checks there.

If the error stays, deactivate plugins (Step 4), raise the memory limit (Step 6) and ask your host for the server error log, which names the real cause. Our WordPress internal server error guide goes deeper into each fix.

Error Establishing a Database Connection

WordPress cannot reach its database. Open wp-config.php and confirm that DB_NAME, DB_USER, DB_PASSWORD and DB_HOST match the database details in your hosting panel. A password changed in the panel but not in wp-config.php, or a wrong DB_HOST after a migration, is the usual story. If the details are correct, the database server may be down or over its quota, which only your host can confirm.

If wp-admin instead reports that one or more database tables are unavailable, the database may need a repair. Add the line below to wp-config.php, visit yoursite.com/wp-admin/maint/repair.php, run the repair, then delete the line, because the repair page works for anyone while it is enabled.

define( 'WP_ALLOW_REPAIR', true );

A connection error that keeps coming back with correct credentials can also signal a compromised site, especially alongside unknown admin users or spam redirects. In that case, follow our first-hour response plan for a hacked WordPress site before you change anything else.

Briefly Unavailable for Scheduled Maintenance

WordPress creates a temporary .maintenance file in the site root during every update and deletes it when the update finishes. If the update is interrupted, the file stays and the site shows this message indefinitely. Wait a few minutes in case the update is still running, then delete .maintenance over FTP. It is a hidden file, so turn on “show hidden files” in your FTP client or File Manager. With WP-CLI, wp maintenance-mode deactivate does the same. Afterwards, open Dashboard > Updates and rerun any update that did not complete.

Too Many Redirects and Login Loops

The browser gives up after being bounced between addresses, or the login page keeps reloading. Check Settings > General: WordPress Address (URL) and Site Address (URL) should match, including https and www. If you cannot reach the dashboard, set both in wp-config.php, replacing example.com with your domain:

define( 'WP_HOME', 'https://example.com' );
define( 'WP_SITEURL', 'https://example.com' );

If the loop started after you enabled HTTPS on a site behind Cloudflare, check the SSL/TLS mode. Flexible mode sends traffic to your server over HTTP while WordPress redirects it back to HTTPS, which creates an endless loop. Full or Full (strict) mode fixes it. For login loops, also clear your browser cookies for the site and rule out a security or redirect plugin with Step 4.

404 Errors on Posts and Pages

If your homepage loads but posts return “Page not found”, the rewrite rules behind pretty permalinks are broken, often after a migration or after installing a plugin that registers custom post types. Go to Settings > Permalinks and click Save Changes without changing anything to rebuild them. If that fails on an Apache server, check that .htaccess contains the default WordPress rules and that mod_rewrite is enabled. For a single missing address, the content was usually moved or deleted, so add a 301 redirect to its new URL. Our guide on how to fix WordPress posts returning a 404 error walks through each scenario.

403 Forbidden

A 403 means the server understood the request but refuses to serve it. On WordPress, the usual causes are wrong file permissions, a rule in .htaccess, or a security plugin or host firewall blocking the request. Over FTP, reset permissions to 755 for folders and 644 for files, rename .htaccess as described for the 500 error, and deactivate security plugins with Step 4. If the 403 only appears for you, your IP address may have been blocked after failed login attempts, so try another network and ask your host or CDN to check its firewall log. Our guide on how to fix the 403 Forbidden error in WordPress covers the permission steps in detail.

502, 503 and 504 Errors

These come from the server layer rather than WordPress itself. A 502 Bad Gateway means the web server got no valid response from PHP, a 503 Service Unavailable means the server is overloaded or deliberately offline, and a 504 Gateway Timeout means PHP took too long to answer. Reload after a few minutes and check your host’s status page first.

If the errors keep coming back, check resource usage in your hosting panel, pause heavy jobs such as backups, imports and scheduled tasks, and look for traffic spikes from bots. Plugins that run slow database queries or call external services can also cause timeouts, so Step 4 still applies. If you use Cloudflare, errors in the 52x range, such as 521 and 522, describe Cloudflare’s connection to your server, not a WordPress problem. Our guide to handling the 503 Service Unavailable error explains the fixes and how to keep planned downtime from hurting your rankings.

Syntax Errors After Editing Code

A message such as “Parse error: syntax error, unexpected…” appears the moment broken PHP is saved, often in a theme’s functions.php. The message names the file and the line. Open that file over FTP and undo your change, or upload the copy you saved before editing. PHP often reports the line after the real mistake, so check the line above it too. Curly quotes copied from a web page, a missing semicolon and a missing bracket cause most of these errors.

To avoid a repeat, keep custom code out of theme files and use a snippets plugin or a small site-specific plugin instead, as explained in our guide to adding custom code to WordPress safely.

HTTP Error When Uploading Images

If the Media Library shows “HTTP error” or an upload fails without a clear message, try again after a minute, because a brief server hiccup is a common cause. If it keeps failing, resize the image before uploading, since very large photos can exhaust PHP memory while WordPress creates the smaller sizes, and raise the memory limit (Step 6). Check that the wp-content/uploads folder is set to 755 so WordPress can write to it, and temporarily deactivate security and image optimization plugins to rule them out.

A message saying the file exceeds the maximum upload size for this site is a different limit. It comes from the upload_max_filesize and post_max_size settings in PHP, which your host can raise.

Your Site Works but Does Not Appear on Google

This one is not an error message, but it sends plenty of site owners looking for one. If a new or recently rebuilt WordPress site is missing from search results, check whether WordPress is asking search engines to stay away.

In the dashboard, go to Settings > Reading.

WordPress dashboard Settings menu with the Reading option selected

Scroll to Search engine visibility, make sure the box next to Discourage search engines from indexing this site is unchecked, and click Save Changes.

Search engine visibility checkbox on the WordPress Reading settings screen

Developers tick this box while building a site so unfinished pages stay out of search results, and it is easy to forget at launch. WordPress itself notes that search engines decide whether to honor the request, so treat it as a launch checklist item, not a privacy tool. Once it is unchecked, request indexing for your homepage in Google Search Console to speed things up.

How to Prevent Common WordPress Errors

  • Test updates on staging first, especially major plugin, theme and PHP updates, and update one item at a time on the live site so you know what broke.
  • Keep automatic backups stored off the server, and test a restore at least once so you know it works.
  • Delete plugins you do not use. Every active plugin is one more chance of a conflict.
  • Check Tools > Site Health once a month. It flags an outdated PHP version, failed background requests and a debug log left open to the public.
  • Turn off the dashboard file editor on live sites with define( 'DISALLOW_FILE_EDIT', true ); in wp-config.php, so nobody can break the site by editing PHP in the browser.
  • Use an uptime monitor that alerts you by email or phone, so you hear about an error before your visitors do.

Most WordPress errors follow the same pattern: a recent change, a fatal error in one plugin or theme, and a message that points straight at it once the log is on. Back up, name the last change, read the log, then isolate plugins and the theme. That routine resolves most problems without outside help, and it teaches you how WordPress fits together, so the next unfamiliar error feels a lot less intimidating.

Still Stuck? Recovery Emails, Backups, Plugin Data and When to Call Your Host

What causes most WordPress errors?

Plugins and themes, usually right after an update, a new install or a PHP version change. That is why the troubleshooting workflow isolates plugins and the theme first. Server problems, such as a database that is down or a memory limit set too low, come next.

Why didn’t I receive the WordPress recovery mode email?

WordPress sends it to the Administration Email Address in the General settings screen, which may be an old or unmonitored inbox, so check that address and its spam folder. Many servers cannot send email reliably without an SMTP setup, so the message may never leave the server. Developers can route it to another inbox with the RECOVERY_MODE_EMAIL constant in wp-config.php. If it still does not arrive, use the debug log and FTP steps instead.

Can I fix WordPress errors without FTP?

Often, yes. Your host’s File Manager can rename folders and edit wp-config.php in the browser, phpMyAdmin can deactivate every plugin, the recovery mode link gives you dashboard access with the faulty plugin paused, and WP-CLI handles most steps over SSH. The free Health Check and Troubleshooting plugin can also disable plugins and switch themes for your session only, while visitors keep seeing the normal site.

Will deactivating plugins delete my settings?

No. Deactivating a plugin, or renaming the plugins folder, leaves its settings and content in the database, and they come back when you reactivate it. Deleting a plugin is different, because some plugins remove their data when they are uninstalled.

Should I restore a backup instead of troubleshooting?

Restore a backup when you need the site online immediately and you know the backup was taken before the change that broke it. You will lose any posts, orders or comments added since then, and the same update can break the site again the next time it runs. Restore first if you must, then reproduce the problem on a staging copy and find the cause before you update again.

Is it safe to delete the .maintenance file?

Yes, once the update has had a few minutes to finish. The file only tells WordPress to show the maintenance message. Deleting it does not complete the interrupted update, so rerun the update from the Updates screen in the dashboard afterwards.

When should I contact my hosting provider?

Contact your host when you see 502, 503 or 504 errors, a database connection error with correct credentials, an error that persists with every plugin off and a default theme active, or anything that points to resource limits. Send the URL, the exact time of the error, the full message and what you already tried, so support can find the matching lines in the server logs quickly.

Larissa Lopes

Written by

Larissa Lopes

A content writer and digital strategist at Visualmodo, covering web development, WordPress, SEO, and digital marketing. She translates complex technical concepts into clear, actionable guidance for developers and site owners. From plugin reviews and web analytics to domain strategy and social media growth, Larissa writes with a consistent reader-first approach while keeping her audience informed on emerging trends in cryptocurrency and fintech.

Topics
Continue reading 5 WordPress Performance Metrics to Track (and What to Do When They Drop)
Continue reading How to Add Custom Code to WordPress Safely Without Breaking Your Site
Continue reading 7 Key Advantages of Accessible WordPress Themes (and How to Test One)
Continue reading WordPress Debug Mode: How to Enable It, Read debug.log and Turn It Off Safely
Continue reading How to Improve WordPress SEO Rankings: What to Fix First

Recommended For You