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.
- Elementor stuck on the loading screen: how to find the cause and fix itWhen Edit with Elementor never finishes loading, one of the editor's requests has failed or one of its scripts has stopped. The browser's Console and Network panel and Elementor's Safe Mode show which. Then one fix applies, most often a plugin conflict, memory, or a blocked request.
- 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 "Another update is currently in progress" in WordPressWordPress locks its own update while one runs, and this message means the lock is set. If an update is running, let it finish. If one was cut short, WordPress honors its lock for 15 minutes, then lets the next update through. To go sooner, delete the option core_
updater.lock. - 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 "Could not create directory" in WordPressWordPress asked the server to make a folder during an install or an update, and the server refused. The path printed after the message names the folder. Correct who may write to it, or set aside a wp-content/
upgrade folder WordPress cannot use. Setting folders to 777 is not the 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, the content area was not found in your page" in ElementorElementor draws its editor where the theme prints the page's content. This message means the page that answered the editor has no such place. Switch the page to one of Elementor's own templates, add the content call to the theme, or remove whatever answered in the page's place.
- 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 "Sorry, you are not allowed to upload this file type" in WordPressWordPress accepts a file only when its extension is on its list of allowed types and its content matches that extension. Save the file in a format on the list, or add the one type you need with a short plugin. Leave the check itself switched on.
- 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 413 Request Entity Too Large error in WordPressThe web server, or a proxy in front of it, refused a request larger than its own limit, and the file never reached PHP. Raising PHP's upload_
max_ filesize does not clear it. Send the file over SFTP and install it with WP-CLI, or raise the limit on the server that answered. - 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 editor has encountered an unexpected error" in WordPressThe block editor shows this when one of its scripts fails while the screen is being drawn. Your saved post is untouched in the database. Save a copy first, then read the text behind "Copy error". It names the script that failed, and the folder in its path names the plugin or theme.
- 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 "The preview could not be loaded" in ElementorElementor shows this when the page it loads inside the editor comes back without Elementor's scripts in it. An error, a redirect, another plugin's page or a template with no footer call does that. The line under the heading and one look at the preview address tell you which.
- 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 REST API encountered an error" in WordPress Site HealthSite Health tests the REST API with one request from the server to the site's own address. "The REST API encountered an error" means no answer came back at all. The line that begins "REST API Response:" says why, and each reason has its own fix.
- 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 "This block contains unexpected or invalid content" in WordPressThe editor compared the HTML saved for a block with what the block's code writes today, and the two differ. The saved content is intact, and nothing changes until you press a button. Copy the post first, then choose by what changed the markup.
- How to fix "Update failed: Download failed." in WordPressWordPress could not fetch the package for an update or an install, and stopped before it changed anything. The words after "Download failed." give the reason, such as a blocked request, a timeout, a refusal by the server that holds the file, or a temporary folder it cannot use. Read them first.
- 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 not sending order emailsEither WooCommerce never sent the email, or it sent it and the message did not arrive. Its own log of order emails says which. From there the cause is an unpaid order, an email switched off, a wrong recipient, a site that cannot send mail, a spam filter, or code that stops the email.
- 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.
- How to fix "Your PHP installation appears to be missing the MySQL extension" in WordPressThe PHP that runs the site has no mysqli extension loaded, so WordPress cannot reach its database and stops before it does anything else. Nothing is lost. Switch mysqli on for the PHP version the site really runs, in the hosting panel or through the host.
- How to fix "Your site could not complete a loopback request" in WordPressSite Health asked the server for the site's own wp-cron.php and did not get a 200 back. The line under the message says why, as a cURL error number or a status code. Find what stands between the server and its own address, because scheduled tasks and the file editors rely on the same route.
- "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.
- WooCommerce add to cart not working: find the cause and fix itWhat you see points to the cause. A missing button means a product that cannot be bought or an old theme template. A button that does nothing or spins means a script error or a blocked request. A cart that empties means a cache, a missing Cart page or a lost session.
- WooCommerce order stuck on "Pending payment": how to tell paid from unpaid, and fix the causeAn order is "Pending payment" until WooCommerce is told the payment succeeded. A stuck one was either never paid, which is normal, or was paid and the payment provider's notification never reached your site. The provider's own record of the payment tells you which.
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. - How to update the PHP version of a WordPress siteThe PHP version is changed in your hosting account, not in WordPress. Update WordPress, the plugins and the theme first, try the new version on a staging copy with the debug log on, then switch at the host and check the site. The same menu sets the version back.
- 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.
- WordPress uptime monitoring: what a check sees and what it missesAn uptime monitor is a service outside your server that asks for your site every few minutes and alerts someone when it gets a server error or no answer. Have it send a GET request, look for words on the page, and ask for one address no cache keeps.
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.
Terms
- Database table prefixThe table prefix is the few characters at the start of every WordPress database table's name, wp_ unless it was changed at setup. It is set in wp-config.php and it is also written inside the database, which is why changing it by hand locks administrators out.
- debug.logdebug.log is the file where WordPress records PHP errors, warnings and notices while its debug log is switched on. It is the first place to look when a page is blank or shows a critical error, and by default anyone who knows its address can read it.
- Heartbeat APIThe Heartbeat API is a script in the WordPress dashboard that checks in with the server on a timer. WordPress uses it to keep post locks, carry autosaves and notice an expired login. Each check-in is a request to admin-ajax.php, which is why it shows up in load problems.
- .htaccess.htaccess is a settings file the Apache web server reads from a website's own folder each time a page is requested. WordPress writes its permalink rules there. One line the server cannot read takes every page of the site down.
- Must-use plugin (mu-plugin)A must-use plugin is a PHP file in wp-content/
mu-plugins that WordPress runs on every request. It is always on, cannot be deactivated from the dashboard and gets no update notices, so it is the plugin most easily overlooked. - PermalinkA permalink is the full, permanent address of a post, page or archive on a WordPress site. One setting decides the pattern every post's address follows, and changing that pattern changes the address of every post at once.
- PHP memory limitThe PHP memory limit is the most memory one request to a site may use before PHP stops it. WordPress asks for 40 MB on ordinary pages and 256 MB in the dashboard unless you set otherwise, and it can only raise the limit as far as the host allows.
- REST APIThe WordPress REST API lets programs read and change a site by exchanging JSON with addresses under /
wp-json/ . The block editor is built on it. When a firewall, a plugin or a missing rewrite rule blocks it, saving and publishing fail. - wp-config.phpwp-config.php is the file that holds a WordPress site's own settings, starting with the database name, user and password. WordPress reads it at the start of every request, so one wrong character in it can take the whole site down.
- WP-CronWP-Cron is WordPress's scheduler. It publishes scheduled posts, checks for updates and runs plugins' timed jobs. It has no clock of its own. Page loads start it, so on a quiet site, or one that cannot reach itself, tasks run late or not at all.
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.