A Theme Update Broke My Site. What Now?
If your site is broken right now, skip to the next section. The order that matters is get it back, then find out why, and people reliably do those the wrong way round: an hour of investigation while the site is down, when reverting takes two minutes and costs nothing. Nothing here is lost by putting the old theme back first.
Two minutes that save an hour
Before you change anything, capture what you are looking at. It costs almost nothing and it is the difference between diagnosing this and guessing at it, because the evidence disappears the moment you revert.
- Screenshot the error. The whole page, including any file path and line number. Those two details are the entire diagnosis and they will not be on screen once the old theme is back.
- Note the time. Server logs are searchable by timestamp, and knowing the minute turns a needle in a haystack into a lookup.
- Write down what you updated. Theme only, or theme and four plugins? If you cannot remember by the time you are debugging, you have lost the most useful clue you had.
- Check whether the admin still loads. Try
/wp-admin/. A working dashboard with a broken front end is a different problem from both being down, and it decides which of the four recovery routes you need.
None of this fixes anything. All of it means you only have to break the site once.
Get it back first
Four ways in, in order of how much access you still have. Use the first one that works.
1. Check your email for a recovery link
Since WordPress 5.2 there is a feature almost nobody knows exists. When a fatal error occurs, WordPress emails the site administrator a special login link, pauses the offending theme or plugin, and lets you into the dashboard to fix it. The announcement of fatal error recovery mode explains the mechanism.
Look in the inbox of the address under Settings, General, which is often not the address you use day to day. Check spam. If the email is there, this is the easiest route by a wide margin.
2. Switch theme from the dashboard
If you can still log in, and the breakage is on the front end only, go to Appearance, Themes and activate any default theme such as Twenty Twenty-Four. The site will look wrong and it will work, which is the correct trade at this point.
3. Switch theme with WP-CLI
If you have SSH, this is the fastest route of all:
wp theme list
wp theme activate twentytwentyfourThe WP-CLI theme command works even when the dashboard does not, because it bypasses the front end entirely.
4. Rename the theme folder
The one that always works, and the one to use when you cannot log in at all. Over FTP or your host's file manager, go to wp-content/themes/ and rename the active theme's folder, for example from mytheme to mytheme-off.
WordPress cannot find the theme, so it falls back to a default one automatically. There must be a default theme present for this to work, which is the reason not to delete them all in a tidying mood.
This is safe. Renaming the folder changes nothing about your content, and renaming it back restores the theme exactly as it was.
Now find out what actually happened
With the site up, you can take your time. The goal is a specific error message, because everything after this is guesswork without one.
Turn on the error log
Edit wp-config.php and add these above the line that says to stop editing:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );That writes errors to wp-content/debug.log without showing them to visitors, which matters on a live site. Reactivate the broken theme briefly, load the page that fails, then switch back and read the log. WordPress's debugging documentation covers the options in full.
Turn all three off again when you are finished. A debug log left running fills up, and one left displaying leaks file paths to anybody who triggers an error.
Read the error, not the symptom
A fatal error names the file and the line. That single line tells you which of the causes below you have, and it converts an afternoon of trial and error into a five minute fix.
The four things it usually is
| Error looks like | Usually means |
|---|---|
| Syntax error, unexpected... | PHP version mismatch. The new theme needs a newer PHP than the server runs. |
| Call to undefined function | A child theme or a plugin is calling something the update removed or renamed. |
| Cannot redeclare function | The same function defined twice, usually a child theme duplicating a parent function. |
| Site loads but looks wrong | Not a PHP error at all. Cached CSS, or customiser settings the new version stores differently. |
PHP version mismatch
The most common, and the least obvious, because the theme update is the trigger rather than the cause. A theme dropping support for an old PHP version is doing the right thing; your server being on that old version is the actual problem. Our guide to checking your PHP version covers where to look, and the fix is usually to upgrade PHP rather than to hold the theme back.
A child theme calling something that has gone
If somebody built a child theme, it may override a parent function or hook that the update renamed. This produces "call to undefined function" and it is a real fix rather than a revert: the child theme needs updating to match. Worth knowing that this is the cost side of child themes, which are otherwise the right way to customise.
A plugin conflict wearing a theme's clothes
Sometimes the theme is fine and a plugin was relying on something in the old version. Test by activating the updated theme with all plugins disabled. If it works, re-enable them one at a time. Tedious, and it takes ten minutes and gives a definite answer.
It loads but looks wrong
Not a fatal error, so nothing appears in the log. Almost always caching: your caching plugin, your host's cache, or a CDN still serving the previous stylesheet. Clear all three in that order. Our guide to clearing the WordPress cache covers the layers, and there are usually more of them than people expect.
If it survives a full cache clear, check the customiser. Some updates reorganise where settings are stored, and options set in the old version can end up unset rather than lost.
Do not simply re-run the update
The strong temptation once the site is back is to try again and hope. Sometimes that works, because the first attempt failed partway and left a half-written folder. Usually it reproduces the fault exactly, on a live site, in front of customers.
If nothing has changed since the first attempt, nothing will change on the second. Fix the cause you found in the log, or test on a copy first.
Going back to a specific version
Reverting to a default theme gets the site up. It does not get your design back, and at some point you want the previous version of your actual theme rather than the broken one.
Free themes from WordPress.org. Every previous release is public. On the theme's directory page there is a development or advanced view listing older versions, each downloadable as a zip. Download the version you were on, then upload it under Appearance, Themes, Add New, Upload.
Commercial themes. Most vendors keep previous releases in your account area alongside the current one. If they do not list them, support will usually send one, and it is a reasonable thing to ask for.
From your own backup. Often the fastest route if you took one before updating. You want only wp-content/themes/yourtheme/ out of it, not a whole-site restore, because a full restore also rolls back any content published since.
Whichever route, treat the old version as a pause rather than a destination. You are back on a release that will stop receiving security updates the moment the next one ships, which puts you on the road to an abandoned theme by choice. Fix the underlying cause, then update properly on staging.
Doing it safely next time
Three habits, in order of how much they help.
Update on a staging copy
The one that actually prevents this. Most decent hosts offer one-click staging: a duplicate of the site on a private address. Update there, click through the pages that matter, then repeat on live. It turns a gamble into a rehearsal, and it is the single biggest difference between a site that goes down after updates and one that does not.
Keep a backup you can restore in minutes
Not the host's, necessarily, and definitely not one nobody has ever restored. A backup taken immediately before the update is the difference between a two minute rollback and an afternoon. Our guide to backups covers what a working one looks like, and the section on testing restores is the relevant part.
Update one thing at a time
When six plugins and a theme update together and the site breaks, you have no idea which one did it and you are back to disabling things one by one. Theme separately, plugins in small batches, and check between each. It takes longer on the days nothing goes wrong and saves the whole afternoon on the day something does.
When to stop and get help
Honest markers rather than a sales pitch. Stop and ask somebody if:
- You cannot get the site back at all, including by renaming the theme folder. That points at something other than the theme, and continuing to change things makes the eventual diagnosis harder.
- The site is a shop and it is down. The cost of an hour of learning exceeds the cost of the call.
- The error names a file you have never heard of, particularly in
wp-includesorwp-admin. That is not a theme problem. - It broke, you fixed it, and it broke again. Something underneath is unresolved and the theme is the symptom.
If the site is down right now and you would rather hand it over, urgent support is what that is for. If you would rather this stopped being your problem in general, a care plan means updates are rehearsed on a staging copy before they touch the live site, which is the version of this article where nothing breaks.
How do I undo a WordPress theme update?
You cannot undo the update itself from the dashboard, but you can stop the broken theme running, which has the same effect. If you can log in, activate a default theme under Appearance, Themes. If you cannot, rename the theme's folder in wp-content/themes/ over FTP and WordPress falls back to a default automatically. To get the previous version back properly, restore from a backup taken before the update, or download the older release from the vendor.
My site is a white screen after updating. What do I do?
Check the administrator email first. Since WordPress 5.2, a fatal error triggers an email with a recovery mode link that pauses the offending theme and lets you into the dashboard. Look at the address under Settings, General, which is often not the one you use daily, and check spam. If there is no email, rename the theme folder over FTP. That always works and changes nothing about your content.
Why did the theme update break my site when it worked before?
Usually PHP. The new version requires a newer PHP than your server runs, and the theme dropping old support is reasonable while your host being behind is the real issue. The other common causes are a child theme calling a function the update renamed, a plugin relying on something the old version provided, and caching serving the previous stylesheet. Turning on the debug log gives you the specific error, which tells you which of the four you have.
Is it safe to rename the theme folder?
Yes. Your posts, pages and settings live in the database and are not touched. WordPress simply cannot find the active theme, so it activates a default one instead, and renaming the folder back restores everything exactly as it was. The one requirement is that a default theme such as Twenty Twenty-Four is still installed, which is the reason not to delete them all when tidying up.
Should I just try the update again?
Only if you have reason to think the first attempt failed partway, which does happen and leaves a half-written theme folder. Otherwise, if nothing has changed since the first attempt, nothing will change on the second, and you will reproduce the fault on a live site in front of customers. Read the debug log, fix the cause, or test the update on a staging copy where breaking it costs nothing.
How do I stop this happening again?
Update on a staging copy first. Most decent hosts offer one-click staging, and clicking through the important pages there turns a gamble into a rehearsal. Keep a backup taken immediately before any update, and one you have actually restored at least once. Then update one thing at a time: theme separately, plugins in small batches, checking in between, so that when something does break you already know what caused it.