Give your WordPress site its first task.
Connect the site you already have, add your agent to Slack or Telegram, and tell it what you need.
Connect your siteStart with 500 free credits. No credit card needed.
On this page
Key takeaways
- A theme update replaces the theme’s files, so any edit made directly in them is gone. WordPress’s Updates screen documentation warns about this.
- A child theme keeps your files from being overwritten. It doesn’t make them compatible with a changed parent. One Neve user had a child theme, cleared every cache, and still saw buttons, menus and spacing change.
- Back up right before the update, not the night before. Kinsta’s docs note a daily backup can be up to a day old, and on a store, pushing a whole staging database to live can wipe out the orders placed since.
- Read the error before you retry. ‘Could not create directory’ means permissions or ownership. A 504 timeout may hide an update that actually finished.
- If the site breaks, roll back first (from your backup, or with WP Rollback for WordPress.org themes) and debug on a staging copy.
The WordPress.org theme directory put 37,210 theme updates live in 2024. Most went through without anyone noticing. The ones that didn’t usually broke something quietly: a menu that changed shape, a button that lost its style, a checkout field that vanished while the homepage still looked fine.
Clicking Update is not the risky part. The risk is in four things around it: where your customizations live, whether you have a backup you can restore, whether you tested on a copy first, and whether the server can write the new files. This guide covers each one, then what to do when an update fails or breaks the site.
Are you updating your theme or replacing it?
“Upgrade” can mean two different jobs, and they need different plans.
Updating means installing a newer version of the theme you already use. It’s maintenance. You back up, protect your custom code, test, and click. Most of this article covers that job. For the click-by-click version, see our guide on how to update a WordPress theme.
Switching means moving to a different theme, or redesigning the site. That’s a project. Menus may need reassigning. Content built with a theme’s own builder or custom post types may not carry over. If any URLs change, you also need redirects. A theme update on its own doesn’t change URLs, so it doesn’t need that SEO work.
What survives a theme update, and what doesn’t
The update replaces the theme’s folder with the new version. Whether a customization survives depends on where it’s stored.
| Where the customization lives | What the update does to it |
|---|---|
| Edits inside the parent theme’s files (functions.php, style.css, templates) | Overwrites them. They’re gone unless you have a backup. |
| A child theme’s files | Leaves them alone. They can still break if the parent changed a class, hook or template they rely on. |
| Customizer and theme settings in the database | Usually keeps them. A major redesign of the theme’s options panel may ask you to pick some settings again. |
| Site Editor templates (block themes) | Keeps them in the database, and they take priority over the theme’s files. One 2025 support thread reports them lost anyway, so back up regardless. |
| WooCommerce template overrides in the theme | Leaves your old copies in place. They don’t pick up WooCommerce’s newer template changes. |
Two details catch people out. First, if you create a child theme after an update has wiped your edits, the edits don’t come back. Second, the Site Editor rule works in reverse: if you saved a customized template, the theme’s new version of that file won’t show on the front end. That’s why some people update a block theme and see nothing change. Check Appearance → Editor → Templates for a customized copy, and decide whether to keep it, revise it or reset it.
If you’re not sure where your changes live, our explainer on theme customization that survives updates shows how to find each layer.
Before you click Update
What you need: an administrator login for the dashboard. For a stuck update or a permissions fix, you also need file access through your host’s file manager, SFTP or SSH. For a premium theme, you need a valid license.
- Write down the current version. Go to Appearance → Themes, open the theme’s details and note the version number. If a child theme is active, note the parent too.
- Find edits in the parent theme. If anyone edited the parent’s files directly, through Appearance → Theme File Editor, a file-editor plugin or FTP, move those changes into a child theme or a snippets plugin first. Add only your own code to the child theme. The Child Themes handbook warns that copying the parent’s whole functions.php causes fatal errors from functions declared twice.
- Read the changelog. Look for removed features, changed templates and new minimum WordPress or PHP versions.
- Take a fresh backup of files and database, and know how to restore it. In one WordPress.org thread, a normal backup restore failed and the host had to rebuild the site. Our explainer on what a backup plugin covers explains why a backup job that “succeeded” can still leave you without a site.
- Test on staging if the site sells or is heavily customized. Refresh the staging copy from live first, run the update there, and check it. Then run the same update on live. On a store, don’t push the staging database over the live one. Kinsta’s documentation warns that a full-database push overwrites live orders, comments, form entries and users.
How to run the update
For a theme from the WordPress.org directory, go to Dashboard → Updates, tick the theme and click Update Themes. You can also use Appearance → Themes, where an update banner appears on the theme’s card. You don’t need to deactivate a child theme to update its parent.
Premium themes update through the vendor’s updater, and that only works with an active license. If no update appears, check the license before anything else. Downloading the package from your vendor account and uploading it is a legitimate alternative.
Update one high-risk thing at a time. If you update the theme, WooCommerce and a page builder together and checkout breaks, you won’t know which one did it. Theme and plugin updates share the same screen and fail in the same ways, so they need the same discipline. If you’d rather not run this routine yourself, SiteSelf handles plugin and theme updates through chat and reports what changed and what it checked.
What a correct result looks like
The success message only tells you the files were copied. It doesn’t tell you the site works. Check these on desktop and mobile:
- The homepage, one post, one page and an archive.
- The main menu, including dropdowns.
- Every form, all the way through submission and the email that follows.
- On a store: a product page, cart, checkout and My Account. Place a test order.
- The PHP error log, for new warnings or fatal errors.
Then go back to Appearance → Themes and confirm the version number moved. On WooCommerce, open WooCommerce → Status. The System Status report lists template overrides in your theme and flags any that are out of date.
What the error message tells you
Failed updates leave specific messages, and each one points to a different fix. Retrying again and again, or loosening permissions across the board, often makes things worse.
| What you see | What it usually means | What to do |
|---|---|---|
“Could not create directory”, or mkdir_failed_ziparchive in Site Health | WordPress can’t write to wp-content because of permissions or file ownership | Ask your host to fix ownership. WordPress’s handbook gives 755 or 750 for directories and 644 or 640 for files. Never set 777. |
| A checksum mismatch, or “The package contains no files” | The download was blocked, cut short or couldn’t be stored | Check disk space, outbound connections and any security plugin or firewall that might block it |
| No update offered for a premium theme | An expired or unregistered license, or the vendor’s updater is blocked | Renew or re-enter the license, or download the package manually from your vendor account |
| “Update failed: 504 Gateway Timeout” | The server stopped waiting. The update may still have finished. | Check the installed version before you retry |
| “Briefly unavailable for scheduled maintenance. Please check back in a minute.” | The update was interrupted and left a .maintenance file in the site root | Delete .maintenance, then check whether the update completed |
The 504 case is real. In one WordPress.org thread about the X theme, the dashboard said the update failed, but the theme had already moved up to 10.6.4. Retrying a finished update just adds confusion.
Uploading the theme by hand can get you past a permissions error. It doesn’t fix ownership, though, so the same error comes back on the next update. Treat a manual upload as a stopgap and get the host to fix the cause.
How to recover when the update broke the site
Get back to a working state first, and debug afterwards.
- Roll back. Restore the theme files from your backup. For themes from the WordPress.org directory, the WP Rollback plugin can install a previous version. Restore files before you consider restoring the database: on a store, an older database also brings back an older order list.
- Isolate the cause if you can’t log in. Over SFTP or your host’s file manager, rename the theme’s folder in /wp-content/themes/. WordPress falls back to a default theme. If the site comes back, the problem is in the theme or child theme. Our guide to the WordPress white screen walks through this in more detail.
- Fix the child theme against the new parent. In one Astra thread, turning the old child theme back on didn’t help. What worked was updating the parent, creating a new child theme and reapplying the styling.
- Update stale WooCommerce overrides one file at a time. WooCommerce’s template docs say overrides in your theme need updating separately. Back up the old file, start from the current WooCommerce template and reapply your changes. Deleting the override removes your customization. Keeping the old one means missing WooCommerce’s newer changes.
Clearing the cache is worth one try, but it rarely fixes a layout broken by an update. In one Neve thread, the user had cleared every cache and still had a broken design.
When to stop and get help
Call your host when the error is about permissions, ownership, disk space or downloads. Those are server problems, and the host can see things your dashboard can’t. Call the theme vendor when a premium theme’s updater or license fails, or when the changelog doesn’t explain a change in behavior.
Get a developer when several WooCommerce templates are outdated, when nobody knows what was edited in the parent theme, or when the site broke and your backup won’t restore. Take the theme version, the exact error text and the time of the update with you. That turns a vague support request into a quick fix.