Key takeaways
- WordPress’s Updates screen warns that changes made to theme files are lost on update. Edits in the parent theme disappear without any error, so move them into a child theme, a small custom plugin or Additional CSS first.
- A child theme protects you, but it can still break. After a major ColorMag release changed class names, users running child themes lost CSS and menus, and the developer told them to rewrite their custom code.
- Since WordPress 6.3, a manual theme update that fails partway restores the previous version on its own. That does nothing for an update that installs cleanly and then breaks your layout, so you still need a backup.
- On WooCommerce stores, open WooCommerce > Status > System Status after the update and look under Templates. Outdated template overrides can break shipping or checkout even when the theme update itself succeeded.
- Match the exact error message to its cause before you retry. “Could not create directory” means a permissions or disk problem, and “Download failed. Unauthorized.” means a license problem.
The update button is the easy part. WordPress’s own Updates screen warns that any changes made to theme files will be lost, and that warning covers most of the damage people see afterward: a header gone, a mobile menu that stops opening, a custom template back to the theme author’s version. The site still loads, so nobody notices until a customer does.
This guide covers the dashboard update, the manual route, premium themes, what to check afterward, and how to read the error when an update fails.
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. The rest of this guide covers that job.
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.
Answer three questions before you click update
A theme update is low risk when nobody has edited the theme and the site is simple. It carries more risk when the theme has been customized, when it is a premium theme with a license, or when the site is a store. Three questions tell you which case you are in.
Where do your customizations live? If someone edited style.css, functions.php or a template file inside the parent theme, including through Appearance > Theme File Editor, the update overwrites those edits without warning you. Before you update, move them into a child theme (for PHP and templates), a small site-specific plugin (for code snippets) or Appearance > Customize > Additional CSS (for styling). Setting up a child theme does not move existing edits into it. You have to find each edit, copy it across and test it. Our guide to theme customization that survives updates covers where each kind of change belongs.
Whether a customization survives the update 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. |
Where does this theme get its updates? Free themes from the WordPress.org directory update through the dashboard. Themes bought on the WooCommerce Marketplace update through the WooCommerce.com Update Manager. Other premium themes update through their vendor’s license, which is usually tied to one domain. There are three routes in all, and the route you use decides what can go wrong.
| Route | Where it runs | What it depends on | How it usually fails |
|---|---|---|---|
| Built-in updater | Dashboard > Updates, Appearance > Themes, per-theme auto-updates | WordPress.org (or a registered update source), writable files, outbound connections, WP-Cron | Permissions, timeouts, disk space |
| ZIP replacement | Appearance > Themes > Add New > Upload Theme > “Replace current with uploaded” | The correct ZIP, with the same folder name as the installed theme | Wrong package, “Destination folder already exists” |
| Vendor channel | A license-activated updater, a vendor dashboard (such as Avada’s), or a marketplace tool | An active license registered to this domain, and the vendor’s servers | “Unauthorized”, vendor API timeouts, companion plugin version mismatch |
Can you get back? Take a backup of the database and the whole wp-content folder. WooCommerce’s update guide gives the same scope for a manual store backup. Then confirm you can actually restore it. A backup you have never restored is a guess.
For a store or a heavily customized site, run the update on a staging copy first. If your host offers one-click staging, use that. Otherwise a staging plugin will do the job.
How to update a theme from the dashboard
You need an administrator login. No hosting access is needed unless WordPress asks for FTP credentials, which is covered in the errors table below.
- Go to Appearance > Themes. A theme with an update available shows a notice on its card. Click the card, then View details to read the changelog. Look for a major version jump, a new minimum PHP version or a new required plugin.
- Take and confirm your backup.
- Click Update now on the theme card. The other route is Dashboard > Updates: tick the theme under Themes, then click Update Themes.
- Wait until the screen confirms the update is done. Closing the tab while it runs is how sites end up stuck in maintenance mode.
- Clear every cache layer: your caching plugin, the host’s server cache, and any CDN. Then open the site in a private browser window.
You do not need to deactivate a child theme to update its parent. Leave the child theme active and update the parent.
Premium themes follow the vendor’s channel
A premium theme that shows no update usually has a license or connection problem. The theme itself is rarely at fault. For WooCommerce Marketplace themes, WooCommerce’s troubleshooting page lists the usual causes: an expired subscription, the wrong or disconnected WooCommerce.com account, a key assigned to another site, a missing Update Manager, a blocked REST API (load yourdomain.com/wp-json/ and you should see JSON), Plain permalinks, WP-Cron not running, a firewall or security plugin, or restrictive file permissions.
Other vendors bind the license to a domain. After a migration, or on a staging copy, updates can fail with “Download failed. Unauthorized.” until you register the license again for the current URL.
Updating manually with a ZIP
The manual route is fine when the dashboard update is not offered, for example with a premium theme you downloaded from the vendor. Go to Appearance > Themes > Add New > Upload Theme and upload the ZIP. When WordPress recognizes the theme is already installed, choose Replace current with uploaded.
Three mistakes cause most manual failures. The first is uploading the vendor’s full package (theme plus documentation) instead of the installable theme ZIP, which returns “No valid themes found” or a missing style.css error. The second is extracting the ZIP first. The third is deleting the old theme before you upload, which WooCommerce’s theme update guide warns loses your customizations.
Uploading the theme folder over FTP into /wp-content/themes/ also works. Treat it as a workaround: if the dashboard update failed, the reason it failed is still there.
What a correct result looks like
A finished update shows the new version number on the theme’s card under Appearance > Themes. On the site itself, check the pages that earn money or leads, not just the homepage:
- Header, footer and menus, including the mobile menu at phone width.
- One post, one page, an archive and the 404 page.
- Every form, with a real test submission.
- Your browser console and the PHP error log, for new warnings.
Stores need more. WooCommerce’s update guide lists product pages, cart, checkout, payments, shipping, taxes and emails. Then open WooCommerce > Status > System Status and scroll to Templates. If your theme overrides WooCommerce templates and those copies are now outdated, they are flagged there. Update the override to match the current template, or remove or rename it so WooCommerce falls back to its default.
Some breakage stays invisible. In one project’s GitHub issue, an Avada site came through an update with “nothing visibly broken,” yet its pages grew to about 1.46 MB of raw HTML, up from about 0.3 MB. A quick page-weight or speed check after the update catches this kind of regression.
Should you turn on theme auto-updates?
WordPress lets you enable auto-updates per theme from Appearance > Themes. That makes sense for an unedited theme on a simple site with working backups. It makes less sense for a store, a site with template overrides or a page builder, or any site where a broken checkout costs revenue before anyone notices.
Professionals are split. In MelaPress’s 2025 survey of 264 professionals, 32% of web designers and 33% of web developers used automatic updates. Agencies commonly stage risky updates (page builders, WooCommerce, major versions), batch the low-risk ones and keep a 24 to 48 hour rollback window. Waiting forever carries its own risk: a site several major versions behind is much harder to bring up to date than one that has been updated regularly.
What to do when the update fails
Read the exact message before you retry anything. Each message points to a different cause.
| What you see | Likely cause | Fix |
|---|---|---|
| “Could not create directory”, or WordPress asks for FTP details | File ownership or permissions on wp-content/themes and wp-content/upgrade, or a full disk or exhausted hosting quota | Check disk usage before you change any permissions. Old backup archives stored inside the account are the usual cause of a full disk or quota. Then ask your host to correct ownership. Don’t open permissions across the whole site. |
| “Could not copy file” or “unable to copy some files… inconsistent file permissions.” | The web server can’t write to the theme folder | Check Tools > Site Health > Info > Filesystem Permissions, then ask your host to correct ownership. Don’t set folders to 777. WP Engine doesn’t allow it, and it opens a security hole without fixing ownership. |
| “There has been a critical error on this website.” | A PHP, plugin or page-builder conflict with the new version. On premium suites, often mismatched companion plugins. | Use the recovery-mode email link, read wp-content/debug.log, test on a default theme, then deactivate plugins one at a time. For Avada, its FAQ says to delete Avada Core and Avada Builder and reinstall them from the Avada Dashboard. |
| No error, but custom layout or features are gone | Edits in the parent theme were overwritten | Restore the old theme files from backup, move the edits into a child theme, then update again. |
| “Download failed. Unauthorized.” | License expired or registered to another domain | Renew, or register the license again for this URL. |
| “Download failed. cURL error 28: Connection timed out.” | The server couldn’t reach the update source in time. On premium themes the slow side is often the vendor’s API. | Your host can confirm whether outbound connections are being blocked. |
| “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.” | An interrupted update left a .maintenance file behind | Delete .maintenance from the WordPress root (not the theme folder), then run the update again. |
| “Destination folder already exists” or “No valid themes found” | Wrong ZIP, or the upload collided with the existing folder | Upload the installable ZIP and choose Replace current with uploaded. Don’t rename the folder inside the ZIP: that installs a second, separate theme, and on a block theme it can cost you work, because Site Editor customizations are tied to the theme’s identity. |
| Site looks unchanged, or oddly styled | Cache | Purge the plugin, server and CDN caches, then check in a private window. |
Deleting .maintenance brings the site back but does not finish the update. Confirm the version number afterward. A 504 can mislead the other way. 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. For a white screen or critical error, our guide to fixing a WordPress white screen walks through the isolation steps.
Stop and get help when the error log names the theme and you cannot tell what changed, when a restore fails, or when checkout is affected on a live store. Stacking more changes on top of a failure you don’t understand makes the cause harder to find.
How to roll back a theme update
Since WordPress 6.3, if a manual theme update fails partway through, WordPress restores the previous version, which it keeps temporarily in wp-content/upgrade-temp-backup/themes/. That covers a broken install. It does nothing when the update installs cleanly and the new version is the problem.
For that case you have two options. WP Rollback reverts any theme from the WordPress.org directory to an earlier version. It does not cover premium themes. For everything else, restore the backup you took before updating. Once the site is back, reproduce the problem on staging and fix the cause before you try the update again.
How the work changes when an agent does it
Updating a theme takes two minutes. Most of the time goes on everything around it: checking which route applies, reading the changelog, catching the outdated template, clearing three caches and then actually looking at the pages that matter. That’s why updates pile up, and why a two-minute job turns into an afternoon.
SiteSelf handles this as a request in chat. Example request: “Update the parent theme on the live site. Before you do, tell me whether the child theme overrides any WooCommerce templates that will be out of date. Afterward, check the homepage, one product page and the cart, and tell me what changed.”
The agent says what’s about to change and whether it can be undone, then runs the update. A theme update replaces files, so it needs hosting (SSH) access, not just the connector plugin. Afterward it fetches the pages you named and reports what it saw, including any error, and the work is recorded. That’s a fetch of each page, not a screenshot, a device test or a payment run through checkout. You still decide whether the result is right.
It has limits. It works on request and doesn’t watch the site, so it won’t notice an auto-update that misbehaves overnight. It can’t sign in to ThemeForest or any other vendor account, so moving a license to a new domain stays with you. Pages owned by Elementor, Divi or Beaver Builder are refused when the work starts, with the reason given. Theme updates and plugin updates share most of their mechanics: the same Updates screen, the same maintenance file, the same permission failures and rollback tools. So the same routine covers plugins, which is where most update work goes, and the page on WordPress update work shows how a full update cycle runs through chat.