Shopify theme broke after an update: what to check first

Theme update or app update: tell them apart

Work out what changed before you change anything, because the fix depends on it. A theme update changes the theme's own files. An app update changes what the app loads into your theme. Neither comes with a message saying it broke something, so you read the clues.

A theme update is the easier one to spot. When an update is added, Shopify puts a new theme in your draft themes named "Updated copy of" followed by the theme's name, and your live theme is untouched until someone publishes it (Shopify Help Center: Updating themes (opens in a new tab)). If your published theme now carries that name, the break most likely came with the update. Shopify also applies automated updates to fix bugs and security issues. Those show as a notice in place of the version number, and Shopify says they do not change the look of the theme, your content or your settings.

An app update leaves no mark in the theme library. Each app's About page, under Settings and then Apps, lists when it was installed or uninstalled (Shopify Help Center: Uninstalling apps (opens in a new tab)). Shopify's web performance reports also mark app installs, theme updates and new code on their timeline, which helps match a problem to a date (Shopify Help Center: Web performance reports (opens in a new tab)).

The quickest test is to preview the theme you had before the update, if it is still in your library. If the problem shows there too, the theme update did not cause it: look at the apps, or at content someone changed.

Check theme versions and duplicates first

In the Shopify admin, open Online Store. Each theme shows its version number; click it to see whether the theme is up to date or an update is waiting. Only themes installed from the Shopify Theme Store get updates there. A theme bought outside the Theme Store is updated by its designer, and vintage themes are no longer updated by Shopify (Shopify Help Center: Updating themes (opens in a new tab)).

Then look at what the update kept. Changes made in the theme editor are copied to the updated theme: theme settings, sections and blocks, new templates, app embeds, and wording changed in the content editor. Code edits are different. They carry over only when they do not conflict with the update, and the theme card says which happened: "Theme added: code edits successfully included" or "Theme added: code edits could not be included". Code edits include changes an app made to your theme files on your behalf.

If you added custom CSS, check that the selectors it targets still exist in the new version. Shopify's update guidance asks you to do exactly that.

Finally, count your copies. When a new theme is published, the one that was live before moves to your draft themes, and none of its changes are lost (Shopify Help Center: Publishing themes (opens in a new tab)). That old theme is your way back. A store can hold up to 20 themes (opens in a new tab), so if you need room for a duplicate, download an old draft before you delete it: deleting a theme is permanent.

App embeds and app updates

Apps reach your theme in three ways (Shopify Help Center: Extend your theme with apps (opens in a new tab)). App blocks sit inside the sections where you place them. App embeds float over the page or add code without showing anything, such as a chat bubble or a tracking script, and you switch them on and off in the theme editor. Some apps also inject code straight into your theme files.

App blocks and app embeds are theme-editor settings, so a theme update carries them over. They do not follow you to a different theme: after switching themes, each app has to be switched on again in the new one. Shopify loads app embeds just before the closing head and body tags of the page (shopify.dev: Configure theme app extensions (opens in a new tab)), so a misbehaving embed can show up across the store rather than on one page.

Injected code is where updates usually go wrong. It counts as a code edit, so it may be missing from the updated copy, and the app's feature quietly stops working. Code left behind by an app you already removed is a different job, covered in how to remove a Shopify app without leaving its code behind.

To test an app, switch its embed off in a duplicate theme and preview. If the problem goes away, the app is involved: send its developer the theme's name and version number, and what you see.

Restore safely: work on a duplicate theme

If sales are affected, restore first and investigate second. Publish the theme you had before the update from your draft themes; the updated theme moves back to drafts without losing anything. Anything changed in the updated theme since it went live is not in the old one, so note those changes before you switch.

Then fix the update on a copy, never on the live theme. Duplicate the updated theme from its actions menu; Shopify names the duplicate "Copy of" followed by the theme's name (Shopify Help Center: Duplicating themes (opens in a new tab)).

Work through the copy in order. Re-apply each code edit that did not carry over, one at a time, and preview after each. Check custom CSS against the new selectors. Switch app embeds on one by one. Then test the pages that sell, on a phone: the home page, a collection, a product with options, the cart and the start of checkout.

For a single file edited by mistake, the code editor's Timeline view restores an earlier version of that file. It works one file at a time, cannot restore a whole theme or a deleted file, keeps a limited history, and files in the assets folder (images, CSS, JavaScript and fonts) have no Timeline history at all (Shopify Help Center: Editing theme code (opens in a new tab)). That is why the duplicate, not the file history, is your safety net.

Publish the copy only when it passes, and keep the previous theme in your drafts until the store has run normally for a while.

When to bring in a developer

Republishing the old theme and checking theme-editor settings are jobs you can do yourself. Bring in a developer when the theme card said code edits could not be included and nobody knows what those edits did, when the fix means editing Liquid or JavaScript, when an app developer and a theme developer each say the problem is the other's, or when the theme is vintage or from outside the Theme Store and needs moving to a supported one. Moving to a new theme is closer to a redesign than a fix; Shopify store setup, redesigns and builds covers how that work is scoped.

A good developer works the way this guide does: on a duplicate, with the old theme kept as the way back, and with the change shown to you before it is published. To have that done for you, hire a Shopify developer who quotes the job in writing before starting.

Not sure what is wrong yet? The free Shopify store review reads your public storefront and shows which theme is running and which apps are visible from the outside, with no login and no app to install.

Questions about a Shopify theme that broke after an update