WordPress Theme Update Failed: Safe Ways to Recover Without Losing Changes

A failed theme update can leave WordPress showing the old theme version, a stuck maintenance message, or a broken front end. Before retrying the update, protect the site: take a fresh backup, check whether the theme has direct custom edits, and use the least risky recovery path first.

Check whether the update is still pending

If you can access the dashboard, go to Appearance > Themes and look for an update notice on the affected theme. WordPress recommends keeping themes current in its WordPress updates documentation, but you should still back up important sites before running the update again.

If the update notice is gone, reload the dashboard once and check the front end. The update may have completed after a timeout or browser interruption. If the notice remains, continue with the steps below instead of repeatedly clicking update.

Remove a stuck maintenance message

If visitors still see a maintenance message long after the update failed, WordPress may have left a .maintenance file behind.

Use SFTP or your hosting file manager:

1. Open the main WordPress install directory.
2. Look for a file named .maintenance.
3. Download a backup copy of that file.
4. Delete .maintenance.
5. Reload the site and dashboard.

This only clears the stuck maintenance screen. It does not repair an incomplete theme update, so check the site carefully after removing it.

Retry from the dashboard only when the site is stable

Use the dashboard retry when the front end still loads and you can reach WordPress admin.

Go to Appearance > Themes, open the update notice, and run the theme update again. If it fails a second time, stop retrying from the dashboard. Repeated attempts can make it harder to tell whether the real problem is file permissions, an incomplete download, a timeout, a license issue, or a bad update package.

For a commercial theme, also check the vendor license screen or updater plugin. Some paid themes will not download updates unless the license is active and connected to the current domain.

Recover if the updated theme breaks the site

If the dashboard still works, switch temporarily to a default WordPress theme from Appearance > Themes. This gives you access to the admin area while you inspect the failed theme.

If the dashboard is not reachable, use SFTP or your hosting file manager:

1. Open wp-content/themes/.
2. Rename the active theme folder, for example from my-theme to my-theme-disabled.
3. Reload the site.

WordPress should fall back to another installed theme if one is available. After the site is accessible again, reinstall the failed theme from a clean copy or restore the previous version from backup.

Protect customizations before replacing theme files

Do not overwrite a theme folder until you know where custom work lives.

If changes were made directly inside the parent theme, a normal theme update can replace those files. Download a copy of the current theme folder before reinstalling or manually replacing it.

If the site uses a child theme, the safer pattern is different: update the parent theme while leaving the child theme in place. Child themes are the standard way to preserve theme customizations across parent theme updates.

Check these folders before replacing anything:

wp-content/themes/active-theme/
wp-content/themes/active-theme-child/

If you are not sure which theme is active, check Appearance > Themes in the dashboard. The active theme is marked there.

Reinstall the theme manually only when needed

Manual replacement is useful when the dashboard update keeps failing, the theme folder is incomplete, or your host confirms the browser update is timing out.

Before replacing files:

1. Back up the database and wp-content/.
2. Download the current theme folder.
3. Confirm whether the theme came from WordPress.org, a vendor account, or a custom developer.
4. Get a fresh ZIP from the original source.

Then upload the clean theme folder through SFTP or your hosting file manager. Avoid mixing random old and new files unless the theme developer specifically instructs you to do that.

For commercial themes, use the vendor’s current ZIP and license update process. WordPress.org update instructions apply to normal WordPress updates, but vendor themes may also require an active license or vendor updater plugin.

Optional WP-CLI update for SSH users

If you have SSH access and WP-CLI is already available on the server, it can be useful when dashboard updates time out. The official wp theme update documentation covers the command syntax.

Update one known theme by slug:

wp theme update theme-slug

Replace theme-slug with the theme folder name, not the human-readable theme title shown in the dashboard.

To update all themes with available updates:

wp theme update --all

Use --all only when you are comfortable updating every theme at once. If you are troubleshooting one commercial or custom theme, update one theme at a time so you know which change caused a problem.

When to stop and restore

Restore the previous backup instead of continuing to patch the live site when:

• The active theme folder is missing key files after the failed update.
• The update replaced direct code edits and you do not have a separate copy.
• PHP fatal errors continue after switching themes.
• The same update fails through the dashboard and through your host’s normal tools.
• A commercial theme cannot verify its license or download package.

After restoring, test the theme update on staging first. If the failure repeats there, send the exact error text, current theme version, target theme version, and PHP version to the theme vendor or host.