Troubleshooting your online store theme

There are a lot of different circumstances that can cause your theme to not display as expected, leading to elements disappearing or not functioning properly, and various other display issues. This could be due to third-party or app code conflicting with the theme, or custom code customizations. There might also be settings in your Shopify admin that need to be adjusted. For example, you might need to review your translated content, products, collections, menus, or your markets.

If you're still having issues with your theme after reviewing the steps in this guide, then you might need to contact your theme's support team. Learn more about getting support for themes.

Locate the source of the issue

Locating the source of the issue in your theme is the first step to fixing it. Try the following steps to help locate the source of the issue:

  1. You can visit the Shopify status page for any known issues that might affect your storefront. If there isn't any similar issue listed, then you can investigate the issue further.
  2. The issue could be local to your device. Local issues are usually a result of device or browser settings, or internet connection issues. Try the following steps to ensure the issue isn't local and can be replicated on other devices, browsers, or internet connections:
    • Clear your browser cache and cookies. If you're logged in to the Shopify Help Center with your Shopify account, then clearing your browser cache and cookies logs you out of your account. If you're using the virtual Help Center assistant, then clearing your browser cache and cookies resets your chat history and logs you out of your account, and you need to start a new chat with the virtual Help Center assistant.
    • Try incognito mode, another device, or the Shopify app.
    • Try using mobile data or another internet connection.
    • Ensure your browser is up to date.
    • Ensure the browser isn't set to block all cookies, because some apps might not display correctly without cookies.
    • Ensure you aren't using a Virtual Private Network (VPN) or have a firewall activated that blocks Shopify.
  3. If you're still experiencing the issue on other devices, browsers, or internet connections, then the issue isn't a local issue and can be replicated. Replicating the issue on another theme is the next step in locating the source of the issue. Visit the Theme Store and install a new version of the theme and test whether the issue is still present on the latest version of the theme. Installing a different theme, such as a free Shopify theme, is also good practice, because you can determine whether the issue is due to that specific theme or if all themes are experiencing the same issue. After testing out other themes, the following are good next steps depending on how the issue presented:
    • If the issue is only present on your current theme and an updated and uncustomized version of the theme, then you might need to get support for your theme.
    • If your issue is only present on the current theme, then there might be some theme code that is causing issues. If you recently updated your theme code, then you can roll back to an older version of your theme code. If you haven't modifed the code in the theme, then you might want to review your theme settings. For example, if the Add to Cart button isn't displaying, then review the colors for Buttons in your theme settings and ensure they're different and contrasting colors.
    • If the issue is present on all themes, then it might be due to your Shopify admin settings, apps, or other issues.
  4. The issue might be from an app. If you recently installed or updated any apps that affect your storefront, then you might want to uninstall the app temporarily. If the issue isn't present after uninstalling the app, then you can contact the app developer’s support team for more help in getting it to display correctly on your storefront. Learn more about getting help with your apps. If the issue is still present after uninstalling the app, then the app isn’t the source of the issue.

Images not displaying correctly

Images might display differently from what you're expecting, but that might be due to the image itself not being compatible with what you're using the image for in your theme. Ensure the image dimensions are correct in the image you're using. Review the following list of common display issues that might occur when uploading an incompatible image:

  • If your header displays wider on desktop and the logo image displays smaller on mobile than you're expecting, then it might be due to whitespace in the logo image file. Edit the image file to ensure it's cropped around the logo and there is no whitespace.
  • If your slideshow image is being cropped, then this is by design to ensure that the images display the same on mobile as on desktop. Because content displays much smaller on a mobile screen, there is a lot of detail that can be lost by shrinking the content. Instead, the content is cropped to ensure that the details aren't lost. A portrait image, which is taller than it is wide, can also take up significant space on desktop. This is why slideshow images have a maximum height. You can add a focal point to your slideshow images to ensure the focal point is always the center of the slideshow image. If adding a focal point doesn't help, then you can try to find an image that works across all screen sizes. Learn more about best practices for slideshows.
  • If a GIF image isn't displaying correctly and it's been added to your storefront with the rich text editor, such as in the product description or in a blog post, then it might be due to the image size. You can correct this by clicking the GIF in the rich text editor, and then click Edit image. In the Image size dropdown menu, select Original. You can then resize the GIF by clicking and dragging the corners of the image inward to make it smaller or outward to make it larger.
  • If your images have a significant color change on your storefront from your original image, then your images might not be in the standard Red Green Blue (sRBG) colors. To fix this color change, save your file in a photo editing application as a sRBG. Common terms for this are "Web optimize", "Adjust image for Web", or "Save for Web." Learn more about color profiles.
  • If your product images on your collection pages aren't aligning, then you might need to adjust the aspect ratio in the product image files so that they're the same height to width ratio, and then upload the product image again. You can also use an image editing app from the Shopify App Store.

Products or collections not displaying properly

If your products are missing from your storefront, then you might need to review the Status and your Sales Channels in the Publishing section of your product in your Shopify admin. Ensure the product status is Active and that the product is available to the Online Store.

If your collections are missing from your storefront, then you might need to review the Sales channels in the Publishing section of the collection in your Shopify admin. Ensure the collection is available to the Online Store. You might also want to ensure that your collection is added to your menus.

If your collections are displaying but there are products missing, then you might need to review any tag filters for the collection in your Menus settings. Ensure there are no tags in the Filter collection with tags field that might cause products to not display.

If your currency isn't displaying correctly for products or in your collections, then you might want to review the Currency display in the Store defaults section in Settings > General to ensure there isn't any additional code. Learn more about formatting how currency displays to your customers.

If some products or collections are displaying differently than the others, then you might need to review the Theme template assigned to the products or collections in your Shopify admin.

Translated content not displaying properly

If your translated content isn’t displaying properly or is missing from your storefront, then there might be outdated translations or missing translations for the content. The content might also be in a specific template for a market. Whenever you add any new content in your default language, remember to run automatic translation again, or manually add new translations.

The following statuses can apply to translated content:

  • Translated: The content has translations available.
  • Outdated: The content in the default language has been updated, but the translations don't reflect any updates.
  • Untranslated: There are no translations for this content type.

When reviewing your translated content, update any untranslated or outdated content and your translated content should then display correctly.

Learn more about translating and localizing your store.

Updates in theme editor not displaying on storefront

If your storefront and your theme editor aren’t displaying the same information, then review the theme template you're editing. You might need to make edits to update your theme templates to display the correct information. Store contextualization allows you to create different storefronts for different markets and display translated content. You might have been inadvertently working within a specific market or B2B when making updates. Locate the content with the Context drop-down menu in your theme editor to make sure it’s in the correct markets.

Learn more about store contextualization.

Rich text editor

Sometimes HTML code that is added in your rich text editor conflicts with your theme code. If the issue is present on a single page, such as a product page, page, or blog post, then it might be because of extra HTML. This can sometimes be added from copying and pasting text from another site.

Review the HTML code

You can review the HTML code in the rich text editor.

Steps:

  1. Navigate to the page in your admin.
  2. Click </> Show HTML button to review the HTML code.
  3. Locate any HTML code that might cause display issues and remove it.
  4. Click Save.

Clear the formatting

You can highlight a portion of the text and clear the HTML formatting.

Steps:

  1. Navigate to the page in your admin.
  2. Highlight the text with the formatting issues.
  3. Click the 🚫 button.
  4. Click Save.

Learn more about the rich text editor.

Page is redirecting to an unsupported URL

If your storefront includes code that redirects users to URLs that aren't connected to your shop, then verify that the redirect has been deactivated when you visit the theme editor.

For example, this type of redirect might be added to a storefront to direct customers to different Shopify stores depending on their location. This type of redirect code could exist in either your theme or an app that you installed.

To ensure your redirect doesn't interfere with the editor experience, use a reference to the window.Shopify.designMode variable in JavaScript to deactivate the redirect when you visit the theme editor. This variable is set to true when the storefront is loaded in the editor, and false when it isn't.

Code error messages

If there's a syntax error in your theme code, then an HTML error found or Theme error warning message displays in your theme editor. The error message displays the Liquid file that contains the error.

A The theme you're looking for couldn't be found warning message might display when there is any broken HTML. A page can fail to load in the theme editor for many reasons, such as the following reasons:

  • network connection issues
  • invalid Liquid code in your theme

You can locate the code changes in your theme code and correct the code, or revert the file to before the code change.

Steps

  1. Click the .liquid section file that is linked in the error message or review the files for recent changes. This takes you to the Edit HTML/CSS page, and the file opens in the code editor.
  2. Browse through the code in the file and try to find invalid HTML or Liquid. The code editor displays potential syntax errors in red. Common problems include the following:
    • Extra closing HTML tags, for example, a closing </div> without an opening <div>
    • Extra unclosed HTML tags, for example, an opening <div> without a closing </div>
    • Malformed HTML tags, for example, <div class="my-class" without a >
    • Malformed Liquid code
    • Broken HTML in an included theme snippet file
  3. After you've found the problem, correct the code in your theme file, or revert the code by selecting a past version in Recent changes.
  4. Click Save.
  5. Click Customize to return to the theme editor, and confirm that the error message is gone.
  6. Navigate to your storefront to ensure that it's displaying as expected.
Can’t find the answers you’re looking for? We’re here to help.