WordPress errors and troubleshooting
What to do when a WordPress site shows an error, a blank page or will not let you in. Start from the message on the screen, find which of its causes you have, and fix that one.
- By
- WP Ministry
- Published
A broken WordPress site nearly always tells you what is wrong, if you know where it says so. Start with the words on the screen.
If the page shows a message, find it among the error fixes. Each one lists the causes of that message, most likely first, with a fix for each. If you have a line from a log and no idea what it means, paste it into the error message decoder.
If the page shows nothing useful, begin with "There has been a critical error on this website" or the white screen, then turn on debug mode so WordPress writes the real error to a file. Most faults that follow an update come down to one plugin: find which one, and switch plugins off from outside if you cannot reach the dashboard.
If you cannot get into the dashboard at all, locked out of WordPress admin tells you which lockout you have from what the login screen shows.
If the site is down and you want an order to work in, use the site down runbook. After an update that went wrong, use the failed update runbook.
If you would rather hand it over, a one-time fix covers one problem on one site, and emergency support is for a site that is down or a checkout that is not taking orders.
Error fixes
- "Alternate page with proper canonical tag" in Search Console: what it means on a WordPress site"Alternate page with proper canonical tag" is not an error. The address listed is a copy of another page, it says so with a canonical link, and Google agreed and indexed the other page. Google's help says there is nothing you need to do. Look closer only if a page you want found is on the list.
- "Blocked by robots.txt" in Search Console: when it is fine, and how to find the rule on WordPress"Blocked by robots.txt" means Google did not fetch the address because your robots.txt told it not to. For /wp-admin/ and a store's add-to-cart addresses that is intended. If the address is a page you want found, a rule is catching more than it was written for: find the line and change it.
- "Blocked due to other 4xx issue" in Search Console: what it means on WordPress and what to doGoogle asked for the address and got a status code in the 400s other than 401, 403 or 404. On WordPress's own files, such as admin-ajax.php and xmlrpc.php, that is normal and needs nothing. For a real page, find the code, then what sent it, which is often a rule or a firewall.
- "Crawled - currently not indexed" on a WordPress site: what to leave and what to check"Crawled - currently not indexed" means Google fetched the address and chose not to index it. If the addresses listed are feeds and archives WordPress makes by itself, that is the right outcome and nothing needs doing. For a page you wrote, it is Google's judgment, and no setting reverses it.
- How to fix 404 errors on WordPress posts and pages that existWhen posts and pages that exist in WordPress answer "404 Not Found", the content is fine and its addresses are not reaching it. Saving the permalink settings again rebuilds WordPress's list of addresses. If that changes nothing, .htaccess has lost its WordPress rules.
- How to fix "429 Too Many Requests" in WordPressA 429 means something counted the requests from one address and decided there were too many in a short time. WordPress itself sends it only for comments posted seconds apart. Otherwise it comes from the host, a firewall or a plugin. Wait, then find out which one answered.
- How to fix "Allowed memory size exhausted" in WordPressA page needed more memory than PHP is allowed to use, so PHP stopped it. Raising WordPress's memory limit in wp-config.php clears it on most hosts. The error message itself names the file that asked for too much, which tells you what to look at if it comes back.
- How to fix "Are you sure you want to do this?" in WordPressWordPress shows this when a request arrives without a valid security token. Current versions word it "The link you followed has expired." The usual causes are a page left open too long, an upload larger than the server accepts, and a plugin that interferes with the tokens.
- How to fix a WooCommerce checkout that is not workingWhen customers cannot place an order, the cause is usually on the site itself. The Checkout page is not set up, a cache is serving a stored copy of it, a plugin or the theme breaks its script, or PHP fails as the order is saved. Where the order stops tells you which.
- How to fix a WordPress login page that keeps refreshing or redirectingWhen the WordPress login page reloads or sends you back to itself with no error, the login is being lost on the way. Either the browser is not keeping WordPress's cookie, or the form is redirected before WordPress reads it. A private window tells you which side to look at.
- How to fix "Briefly unavailable for scheduled maintenance" in WordPressWordPress puts a site into maintenance mode while it installs an update and takes it out again when the update finishes. If the update was cut short, the site stays in maintenance mode. Removing one small file brings it back.
- How to fix "Cannot modify header information - headers already sent" in WordPressPHP was asked to send a header, such as a redirect or the login cookie, after part of the page had already gone out. The message names two files. The first, after "output started at", is where the stray output came from, and it is the one to fix.
- How to fix "Destination folder already exists" in WordPressWordPress found a folder with the plugin's or theme's name already in place, and stopped before changing anything. If the plugin is installed, activate, update or replace it. If the folder is a leftover from an install that did not finish, move it out and install again.
- How to fix ERR_CONNECTION_TIMED_OUT on a WordPress siteERR_CONNECTION_TIMED_OUT means the browser tried to connect to your site's server and got no answer. WordPress was never reached, so the cause is the server, a firewall, DNS or your own network. Check from a second network first, then follow what that shows.
- How to fix "Error establishing a database connection" in WordPressWordPress reached your web server but could not open its database. Your posts and settings are still there. In most cases the cause is a database name, user, password or host in wp-config.php that no longer matches.
- How to fix ERR_TOO_MANY_REDIRECTS in WordPressERR_TOO_MANY_REDIRECTS means the site keeps sending the browser from one address to another and never to a page. Two parts of the setup disagree about the site's address, usually over https or www. Find the addresses the loop runs between, then make WordPress and the server agree.
- How to fix "Maximum execution time exceeded" in WordPressPHP stopped a request because it ran longer than the server allows, which is 30 seconds by default. The log names the file that was running when time ran out. Raise the limit for a one-off long job. If an ordinary page needs longer, find what is slow instead.
- How to fix "Missed schedule" on a scheduled WordPress postThe post's time passed and WordPress did not publish it. The post is intact. Publish it now, then find the reason. WordPress only runs scheduled tasks when a page is loaded and the site can send a request to itself, and one line in wp-config.php switches that off.
- How to fix "Missing a temporary folder" in WordPressPHP could not create the temporary file that every upload begins as, so WordPress was handed an error instead of a file. The folder is a PHP setting on the server. Defining WP_TEMP_DIR in wp-config.php does not clear the message, because that sets a different folder.
- How to fix mixed content warnings in WordPressMixed content means a page loaded over https asks for an image, a stylesheet or a script over plain http. Browsers block those requests or change them, so parts of the page go missing. The fix is to find where the http addresses come from and correct them there.
- How to fix "Parse error: syntax error, unexpected" in WordPressPHP could not read one file, almost always because code pasted into functions.php or a plugin file has a character missing. The message names the file and the line. Take the new code out, or put a clean copy of the file back, and the site returns.
- How to fix "Sorry, you are not allowed to access this page." in WordPressWordPress shows this when the account you are logged in with lacks the capability a dashboard screen asks for. The account's role is too low, the roles in the database are damaged or stored under an old table prefix, or a plugin is in the way. Nothing on the site is lost.
- How to fix the 403 Forbidden error in WordPressA 403 means the server understood the request and refused it. On a WordPress site the refusal comes from a rule in .htaccess, a security plugin, file permissions or the host's firewall. Who is refused, and on which pages, tells you which one to look at.
- How to fix the 500 Internal Server Error in WordPressA 500 error is the web server saying something went wrong without saying what. On a WordPress site the two usual causes are a damaged .htaccess file and a PHP error in a plugin or theme. Replacing .htaccess with WordPress's standard one takes two minutes and settles which it is.
- How to fix the 502 Bad Gateway error in WordPressA 502 means one server passed the request to another and got no usable answer. On a WordPress site that is usually nginx, or a CDN, failing to get a page from PHP. Your content is safe. Most fixes belong to whoever runs the server, and a few checks tell you what to ask for.
- How to fix the 503 Service Unavailable error in WordPressA 503 means the server is running and cannot handle the request right now, because of maintenance or overload. The words on the page show who sent it. That can be WordPress during an update, a plugin, the web server at a hosting limit, or a service in front of the site.
- How to fix the 504 Gateway Timeout error in WordPressA 504 comes from a server in front of WordPress, such as nginx or a CDN, that stopped waiting for an answer. The work behind it may have finished anyway. Find which request is slow, run a long job from the command line, and raise the wait only where a job needs it.
- How to fix the "HTTP error" when uploading images to WordPressThe uploader got a failed answer from the server, or none, most often because creating the picture's smaller sizes ran out of memory or time. Upload a copy scaled to 2560 pixels, or read the server's real error and fix what it names. Your original file is untouched.
- How to fix "There has been a critical error on this website" in WordPressWordPress shows this message in place of any page that PHP could not finish. It is the same whatever failed. The real error is one line, kept in an email to the site's administrator, in the debug log and in the server's log. Find that line first. It says which fix you need.
- How to fix "The uploaded file exceeds the upload_max_filesize directive in php.ini" in WordPressPHP refused a file larger than its upload_max_filesize setting, and WordPress passed the message on. Raise upload_max_filesize and post_max_size together, in .htaccess, in .user.ini or in your host's PHP settings, depending on how PHP runs. Nothing on the site has been lost.
- How to fix the WordPress white screen of deathA blank page, or "There has been a critical error on this website", means PHP hit an error it could not recover from, almost always in a plugin or the theme. Switching that one plugin or theme off brings the site back. The error log names which one.
- How to fix "Updating failed" and "Publishing failed" in the WordPress editorThe block editor saves through the site's REST API. "Updating failed" means the answer to that request was not the JSON the editor expects. Nothing already saved is lost. Look at what came back instead of JSON, and the fix follows from it.
- How to fix WooCommerce payment gateway errorsThe order is created but the payment is refused, or the money is taken and the order never shows as paid. The order's status and notes say which. Usual causes are mixed-up test and live credentials, payment confirmations that cannot reach your site, and a gateway not offered at checkout.
- How to fix WordPress not sending emailWordPress hands every email to the mail program on its own server. Many hosts restrict that program or do not provide one, and mail sent that way is often treated as spam. A two-minute test shows which problem you have. The lasting fix is a mail service that vouches for your domain.
- How to fix WordPress when it keeps logging you outWordPress keeps you logged in with a cookie that it checks on every page. If you are sent back to the login screen while you work, the cookie has stopped arriving or stopped passing the check. Site addresses that differ, a browser that drops it and security keys that change are the usual reasons.
- How to fix "Your connection is not private" on a WordPress siteThe browser could not verify your site's security certificate, so it stopped before loading the page. A code on the warning says why. The certificate has expired, was issued for a different name, or comes from an issuer the browser does not trust. Most cases are fixed in your hosting panel.
- "Not found (404)" in Search Console: which addresses to fix on a WordPress site, and which to leave"Not found (404)" lists addresses that answered 404 when Google asked for them. Most never were pages or were removed on purpose, and Google's help says such 404s do no harm. Only two kinds need work: a page that moved, which needs a redirect, and a page that should exist.
- "Page with redirect" in Search Console: what it means on a WordPress site, and which ones to fix"Page with redirect" lists addresses that answered Google with a redirect. The address is not indexed. The page it leads to can be. On a WordPress site the list is usually old and alternative addresses that WordPress forwards by itself, and they need nothing. A few can be wrong.
Guides
- admin-ajax.php high CPU usage in WordPress: how to find what is calling itadmin-ajax.php is the address WordPress, plugins and themes use for background requests. High CPU from it means something calls it too often, or one kind of call is slow. Find the action behind the requests, fix whatever sends it, and do not block the file.
- How to change WordPress permalinks without breaking your old linksWordPress keeps no record of a permalink structure you leave. After a change, some old post addresses are forwarded by a guess and the rest answer 404. A move from a dated structure to Post name answers 404. Add one 301 rule for the old pattern, then check an old address.
- How to deactivate WordPress plugins when you are locked out of the dashboardYou can switch plugins off without the dashboard. Use the recovery link WordPress emailed you, WP-CLI, a renamed plugin folder or, last, the list of active plugins in the database. Each keeps the plugins' settings. Then log in and activate them one at a time.
- How to find and fix a WordPress plugin conflictSwitch every plugin off and check that the fault is gone. Then switch them back on in halves until it returns. The plugin whose return brings the fault back is the cause. Update it, go back a version or replace it, and report the fault to its author.
- How to remove the OBJ box from a WordPress title or postThe "OBJ" in a dotted box is an invisible Unicode character, the object replacement character, that came in with pasted or dictated text. Delete it in the editor, check the title and the SEO fields, and paste as plain text from then on.
- How to turn on WordPress debug mode, read the log and turn it offPut three lines in wp-config.php that set WP_DEBUG to true, WP_DEBUG_LOG to true and WP_DEBUG_DISPLAY to false. Errors then go to wp-content/debug.log and stay off the page. Read the newest lines, set WP_DEBUG back to false and delete the log.
- Locked out of WordPress admin: find which lockout you have and get back inWhat the login screen shows tells you which lockout you have. A refused password, a missing reset email, a blocked address, a lost second step, a moved login page and a missing administrator account each have their own way back in. Find yours in the table, then follow that fix.
- Slow WordPress admin: how to find the cause and fix itThe dashboard is never served from a page cache, so every screen waits on PHP and the database. Time one slow screen, read it in Query Monitor, then check outside requests, database queries, the object cache, PHP, Heartbeat, WP-Cron and the host, in that order.
- WordPress hosting problems: how to tell whether the fault is the host or the siteA fault is the host's when it sits in the account, the server, the plan's limits, the mail program or the firewall. It is the site's when it follows a change you made or clears with plugins off. The message on the screen usually says which, and one check settles the rest.
- WordPress site not showing up on Google: what to check, in orderSearch Google for site:yourdomain.com first. If nothing comes back, the site is either new or keeping Google out, through the "Discourage search engines" box, another noindex, a robots.txt rule, or a home page that does not answer with a 200. Check them in that order.
Runbooks and checklists
- A WordPress update went wrong: a runbookWhat to do, in order, when an update to WordPress, a plugin or a theme leaves the site broken or stuck. Stop updating, copy down what the screen says, get back into the dashboard, then choose between going back one version and restoring a backup.
- WooCommerce checkout is down: a runbookWhat to do, in order, when customers cannot pay on a WooCommerce store. Go through the checkout yourself and read the latest orders, work out which of three faults you have, keep orders coming in with a second way to pay, then account for every payment made while it was broken.
- WordPress site down: a runbook for the first hourWhat to do, in order, when your WordPress site stops loading. Confirm it is down for everyone, write down what the screen says, find the layer at fault, and choose the smallest change that brings the site back.
Tools
- WordPress error message and debug.log decoderPaste an error message or lines from your log and see what each one means, which plugin or theme it points at, and what to do first. Read in your browser; nothing is sent.
- WP-CLI command builderChoose a job, fill in what it needs, and copy the WP-CLI command with its flags in place: updates, backups, getting back into a broken site, replacing an address. Built in your browser.
- HTTP status and redirect checkerSee what an address answers and every redirect on the way: each hop, its status code and where it sends you next.