A Shopify theme stops working for a small set of reasons: a Liquid code error, an app conflict, a stale browser cache, a theme update that broke a customization, or a setting in the wrong place. The fix depends on which one. This post walks through the 10 most common theme failures we see, in the order you should check them, with the exact path through the admin to fix each.

We detect themes and apps on real Shopify stores every day, which means we see which apps most commonly cause theme conflicts and which themes break the most often after updates. The diagnostic flow below is built from that pattern, not from theory. Start at the top of the list and stop at the first match.

Key Takeaways
1
Most “theme not working” reports come down to one of five causes: a Liquid syntax error from a recent edit, an app conflict, a stale browser or CDN cache, a theme update that overwrote customizations, or a setting on the wrong product/collection/template.
2
Try the cache fix first. Clear the browser, try incognito, and check the site on a phone. Roughly 30% of “theme broken” reports are local-only display issues that go away on a clean browser.
3
Shopify’s rollback feature only restores Liquid files. CSS and JavaScript edits are not in the rollback history. Back up the theme as a duplicate before any code edit so you have a real safety net.
4
Never edit the published theme directly. Duplicate it, edit the copy, preview, then publish. This is the single change that prevents most theme emergencies.
5
If the editor loads but the live site is broken, the issue is a published theme problem. If the editor itself will not load, the issue is a Liquid error or a network problem.

What Do I Try First When My Shopify Theme Stops Working?

Try the cache and browser fix before anything else. Clear the browser cache, open the storefront in an incognito window, and check the site on a phone on cellular data. About 30% of “my theme is broken” reports are stale local cache that resolve on a clean session. If the issue is still there in incognito and on mobile, it is a real theme problem and the sections below cover where to go next.

If the issue passed the cache test, the next question is whether the theme editor itself loads. If the editor opens but the storefront is broken, the published theme has a problem (skip to the relevant H2 below). If the editor will not load, the problem is upstream of the storefront, and the next section is where to start.

Why Won’t the Shopify Theme Editor Load?

The editor fails to load when there is invalid Liquid code in the theme, a network or CDN issue on Shopify’s side, or a browser/extension blocking the editor’s JavaScript. Liquid errors are the most common cause and Shopify’s code editor highlights them in red on the file that broke.

Fix steps in order:

  1. Try a different browser. Chrome, Safari, and Firefox handle Shopify’s editor differently. An editor that won’t load in Chrome often loads fine in Safari. Rule out the browser first.
  2. Disable extensions. Ad blockers, privacy extensions, and some password managers inject scripts that break the editor’s JS. Try the editor in a clean incognito window with extensions disabled.
  3. Check Shopify’s status page. Go to status.shopify.com. If there is an ongoing incident, the editor may be down for everyone and this is not your problem to fix.
  4. Open the theme’s code editor directly. Go to Online Store > Themes > Actions > Edit code. If this page loads, the editor is fine and the issue is something else (usually a Liquid error in the theme file you last edited).
  5. Look for red Liquid errors. Shopify highlights syntax errors in red in the code editor. If you see one, fix it. Common errors: unclosed if/unless tags, a missing endif, or a filter with wrong syntax.

Why Is My Shopify Theme Not Showing on the Storefront?

The theme is not showing on the storefront when the wrong theme is published, a Liquid error crashed the template, a newly installed app injected broken JS, or a CDN is serving a cached version of the old theme. Check them in this order:

  1. Confirm which theme is published. Go to Online Store > Themes. The published theme has a green “Current theme” badge. If your updated theme is in the unpublished list, you forgot to publish it.
  2. Check for recent app installs. If the theme worked before and stopped working after an app install, go to Online Store > Themes > Actions > Edit code and look for a new script tag in theme.liquid or layout files. Remove it and test.
  3. Test on a different device and connection. CDNs sometimes serve stale cached themes. A visitor on a different ISP may see the current version when you don’t. This is rare but happens.
  4. Try previewing an unpublished duplicate. Duplicate the current published theme, preview it. If the duplicate shows the same issue, the problem is in the theme code. If the preview is fine, the published theme has a corrupted deployment.

Why Are My Shopify Theme Changes Not Showing Up?

Changes not appearing after saving fall into three buckets: browser cache, wrong section/template, or you edited the unpublished theme instead of the published one.

  • Browser cache: Hard refresh with Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac). Then try incognito.
  • Wrong theme: Shopify shows the published theme on the storefront. If you edited a duplicate that is not published, nothing changed on the live site.
  • Wrong template: Shopify themes have separate templates for products, collections, and custom pages. If you edited the default product template but the product is using a different template, your edits apply to the wrong context.
  • Section vs. block scope: Settings in the theme customizer are stored per-section, per-template, and per-page. A color setting in the “Default” homepage template does not apply to a custom page template. Check which template the page is using before hunting for where to change the setting.

Shopify Theme Stopped Working After an Update: What Happened?

Theme updates from Shopify replace all the theme’s Liquid, CSS, and JavaScript files with the new version. If you had customized any of those files directly (not through the customizer), those changes are gone. The customizer settings (colors, fonts, section order) are preserved in the theme’s JSON configuration files, which the update does not overwrite.

What to do after a bad theme update:

  1. Identify what broke. Compare the current published theme to the last-working version. If you kept a pre-update duplicate, open both in preview tabs and compare.
  2. Re-apply file edits. If you had custom code in theme.liquid, product.liquid, or any Liquid file, those need to be re-applied manually to the updated theme. There is no automatic merge.
  3. Check app injection points. Some apps write code into Liquid files. After a theme update, those injection points may have moved or been removed, breaking the app’s rendering.

Why Is a Specific Product Not Showing on My Shopify Theme?

A product that exists in the Shopify admin but does not appear on the storefront is almost always hidden from a sales channel. In the Shopify admin, go to the product and look at the “Sales channels” panel on the right. The “Online Store” toggle must be enabled. If it is off, the product returns a 404 on the storefront even though it exists in the admin.

Other causes of missing products:

  • Wrong template: If the product is using a custom template that has a rendering error, it will not display. Assign the product to the default template temporarily to test.
  • Collection filter settings: The theme’s collection page may be filtering products by availability or tag, hiding products that don’t meet the filter criteria. Clear filters and test.
  • Out-of-stock with “hide when unavailable” enabled: Some themes and apps hide out-of-stock products from the collection grid. Check the theme settings under Collection pages for a hide/show out-of-stock option.

Why Is My Shopify Theme Customizer Not Saving?

The customizer fails to save when the session has timed out, a network error occurred mid-save, or a JavaScript conflict is preventing the save confirmation. Signs of a failed save: the page refreshes after hitting Save but the changes revert, or the Save button spins but never completes.

Fixes:

  1. Hard refresh the customizer tab (Ctrl+Shift+R / Cmd+Shift+R), then make the change and save again.
  2. Log out of Shopify admin, log back in, and try the customizer again.
  3. Try the customizer in a different browser or in incognito mode.
  4. If the issue is persistent, clear Shopify admin cookies and cached data for the shopify.com domain.

Shopify Theme Images Not Loading

Theme images that don’t load fall into two categories: background images set in the customizer (CSS-based) and product/section images added via the image picker (stored in Shopify’s CDN). Background images stop loading when the theme’s CSS has a broken url() reference, usually from a theme update that renamed a folder. Product images stop loading when the CDN URL is malformed or the image was deleted from the media library.

Diagnosis:

  • Open the browser dev tools (F12), go to the Network tab, reload the page, and filter for failed image requests (red rows).
  • For a broken CSS background: right-click the element, Inspect, find the background-image URL in the Styles panel, and paste it in a new tab. 404 means the asset path is wrong.
  • For product images: go to Shopify admin > Products, open the product, and re-upload or reattach the image from the media library.

Shopify Theme Fonts Not Loading

Fonts stop rendering when the theme’s CDN link is blocked, the Google Fonts request fails, or a Content Security Policy on the storefront blocks external font sources. In most cases, a blocked Google Fonts request just falls back to the system font and the page looks off but still loads. True font failures (where the text goes invisible) happen when the font-face declaration uses a format the browser cannot render.

Fixes:

  • Check the Network tab for failed font requests. Look for requests to fonts.googleapis.com or fonts.gstatic.com returning 403 or failing outright.
  • If you’re on a custom domain with a Content Security Policy header, make sure the policy includes fonts.googleapis.com and fonts.gstatic.com in the allowed sources.
  • Try switching the font in the theme customizer to Shopify’s built-in font library instead of Google Fonts. Shopify-hosted fonts load from the same CDN as the theme and are not affected by external CSP blocks.

Theme App Embed Is Showing in Editor But Not on the Storefront

App embeds that appear in the theme editor preview but not on the live storefront are almost always a publish mismatch. The editor and the storefront pull from different source files: the editor shows you what would happen if you publish, the storefront shows the current published version. If you enabled an app embed but didn’t save and publish the theme, the storefront has not received the update.

Fix: In the theme customizer, click Save. Then check that the theme is published (Online Store > Themes > Current theme). If the app embed is still missing on the live site after a confirmed save and publish, clear the storefront cache and try on a fresh browser session.

Shopify Theme Mobile View Is Broken

A theme that works on desktop but breaks on mobile has a responsive CSS problem, a section setting that applies only to mobile, or a third-party script that renders differently on small screens. Breakpoints in Shopify themes are set in the CSS and vary by theme. Dawn’s main breakpoint is 750px. Debut uses 769px. If a layout breaks at exactly the breakpoint, look at the theme’s CSS for the media query handling that width.

Diagnosis steps:

  1. Open dev tools, click the responsive design icon (or press Ctrl+Shift+M), and test at 390px (iPhone 14), 414px (iPhone 12 Max), and 768px (iPad).
  2. In the theme customizer, switch to the mobile view using the device icon at the bottom of the toolbar. Some settings in the theme apply only to mobile: check the section’s settings for any mobile-specific overrides.
  3. Disable third-party scripts one at a time (comment them out in theme.liquid) and refresh. If the mobile layout fixes, the script was the cause.

How to Use Shopify’s Built-In Theme Diagnostics

Shopify added a theme diagnostics tool that flags known issues in your published theme before they cause problems. To access it, go to Online Store > Themes, click the three-dot menu next to your current theme, and select “Theme diagnostics.” The tool runs a scan and returns a list of warnings in a few seconds.

The warnings fall into three categories worth understanding:

  • Deprecated API usage: Shopify periodically retires old Liquid filters, objects, and endpoints. A deprecated API warning means your theme is using something that still works today but will stop working at a future date. Act on these before Shopify sets a removal deadline, not after.
  • App blocks without a published state: An app block that was added to the theme but never published shows up as a warning. This usually means an app was installed, its block was placed in the editor, but the theme was never saved after that change. The fix is to either publish the block or remove it from the editor.
  • Section schema errors: Schema errors in a section’s JSON mean the section’s settings won’t load correctly in the customizer. These are usually caused by a manual code edit that introduced invalid JSON (a missing comma, an extra bracket). Open the section file in the code editor and look for the red underline that marks the bad line.

Not every warning needs immediate action. Deprecation warnings with no stated removal date can be noted and scheduled. Schema errors and unpublished app blocks should be resolved promptly since they affect the customizer and storefront rendering today.

When to Duplicate vs When to Roll Back

Shopify gives you two recovery options when a theme breaks: duplicate the current theme, or roll back to a previous version. They do different things and the right choice depends on what broke and how.

Rollback restores Liquid template files from Shopify’s version history, which goes back 30 days. It does not restore CSS or JavaScript edits made outside of Liquid files, and it does not restore customizer settings stored in JSON. Rollback is also permanent in the sense that it overwrites the current state of the theme with no warning. If you roll back and realize you needed something from the current version, it’s gone unless you kept a duplicate.

Duplicate makes an exact copy of the theme in its current state (Liquid, CSS, JS, and JSON settings). It costs nothing and takes about 10 seconds. The duplicate sits in your unpublished themes list and can be restored by publishing it.

The right sequence when you’ve applied an update that broke the site:

  1. Duplicate the current (broken) theme first. This preserves your current state, including any JSON settings and CSS changes that rollback won’t touch.
  2. Then use rollback on the published theme to restore the last working Liquid state.
  3. If rollback restores the site, open both the rolled-back version and the duplicate side by side and manually re-apply the changes you want to keep.

As a general rule: duplicate before any rollback, before any major code edit, and before any theme update. A duplicate is a free insurance policy and Shopify does not limit how many you can keep.

Shopify Theme Error Messages: What Each One Means

Shopify surfaces error messages in the code editor, the browser console, and occasionally in the storefront itself. Here is what the most common ones actually mean, in plain terms.

Error message What it means Where to look
Liquid error: undefined method A Liquid filter or method is being called that does not exist in this version of Liquid. Usually caused by copying code from a newer theme into an older one, or from a third-party snippet that used a filter Shopify later removed. The code editor will highlight the file. Search for the filter name and replace it with the current equivalent.
Cannot read property of undefined A JavaScript error, not a Liquid error. An app or theme script is trying to access a DOM element or object property that does not exist on this template. Common on collection or product pages where apps expect a specific element ID that the theme does not include. Browser console (F12 > Console). The stack trace shows which script is responsible.
Error: Route not found The template file for the requested URL does not exist. This happens when a product, page, or collection is assigned to a custom template that was deleted from the theme. Go to the product or page in the admin, change the template assignment to “default,” and save. Then add the missing template back in the code editor if needed.
The file you are trying to edit does not exist The file was renamed or deleted, either manually or during a theme update. The code editor still has the old filename in its navigation but the file is gone. Restore the file from a backup duplicate, or copy the equivalent file from a fresh download of the same theme version.
Syntax error: unexpected… A Liquid syntax problem. The most common causes are unclosed block tags ({% if %} without {% endif %}), missing pipes before a filter name, or a variable name with an invalid character. The code editor shows a red underline on the problem line. Fix the tag, save, and reload.
Error 503 / Service Unavailable Shopify’s servers returned a 503, which means the request could not be handled. This is almost always a Shopify-side issue, not something in your theme code. Check status.shopify.com for an active incident. If there is no incident and you’re seeing 503 errors consistently, contact Shopify support with the specific URL and time of the error.

One pattern worth noting: Liquid errors show up in the storefront as inline text (the phrase “Liquid error:” appears where content should be), while JavaScript errors are silent on the page but visible in the browser console. If the page looks wrong but there is no visible error text, always check the console first before looking at Liquid.