November 9th, 2024

Shopify: The Theme you’re looking for couldn’t be found

The Theme you’re looking for couldn’t be found. Check the web address and try again, or try navigating to the Theme Editor from Theme

If you’ve ever been working on a Shopify theme and this seemingly major error occurs, do not fear – there’s a simple fix!

Why Does “The Theme you’re looking for couldn’t be found.” happen?

I’ve searched the web for an answer to this. Even though I didn’t find one, I did get enough insight into the why to understand what happens under the bonnet.

On the surface, what appears to be happening is that something in the theme’s code has changed. And that’s is absolutely the case. But the problem isn’t that the code has changed, it is that the content’s no longer aligned with the theme’s schema!

What’s the theme’s schema?!

In Shopify themes are made up of templates. Most of the templates are for rendering the content – these are Liquid templates (a templating language for building HMTL pages). When these Liquid templates have content in them that’s populated/configured in the visual editor there’s a schema section (typically at the bottom) where the information for the visual editor exists. It is this section that’s at the core of the bug!

Why is the theme’s schema causing the problem?

The problem arises when this schema’s data is not in sync with the theme’s configuration – I’ll come back to this in a bit. As I said earlier, I was not able to find any support from the web about this as the advice fails to provide any actual solutions, even Shopify’s support forums failed to solve the problem – all I found was, “Try clearing the cache”, “Use a private browser window” and so on. None of this worked, and it’s very obvious it wouldn’t because the problem is server-side.

The theme’s config files

Before we proceed to the solution, let’s first familiarise ourselves with the theme’s config files. There are two of them;

settings_data.json and,
setting_scheam.json.

The one we’re concerned with is the first one. This is where settings “values” are stored from the actions taken in the visual editor. This is where we will find the offending data that’s broken the synchronisation between the schema data stored in the Liquid files and the data stored when the theme’s content is edited.

How to recreate a scenario that we can use to introduce the problem

Now the real root of the problem has been unearthed, let’s look at an example to demonstrate how the issue arose and how to fix it.

Step 1: create a new feature in the header.liquid template

Here’s an extract to add a repeater of an image and a link (it could be used to output a list of linked partner icons). Note that this is an example – feel free to reach out for help if you need to know how to build this into a theme and code the Liquid part to render it.

...
"blocks": [
    {
      "type": "example_icon_list_item",
      "name": "Icon",
      "settings": [
        {
          "type": "image_picker",
          "id": "example_icon_image",
          "label": "An Icon",
          "info": "An SVG is recommended"
        },
        {
          "type": "url",
          "id": "example_icon_url",
          "label": "A link",
          "info": "e.g. a link to a partner's website"
        }
      ]
    }
...

Step 2: add values to the new block

With the above configuration added to the header.liquid template, we can now head over to the theme’s visual editor, where we can add some values to this new feature.

Understanding how Shopify stores the data from the theme editor

Now the new feature’s in use, let’s take a look at what Shopify has generated to store the image and link.

At this stage everything is good and the new feature works as expected (just needs to be rendered, which we don’t need to do to recreate the issue).

...
    "sections": {
      "header": {
        "type": "header",
        "blocks": {
          "example_icon_list_nYq7Fx": {
            "type": "example_icon_list_item",
            "settings": {
              "example_icon_image": "shopify://shop_images/icon-shipping.svg",
              "example_icon_image": "shopify://pages/delivery-information"
            }
          }
        },
        "block_order": [
          "example_icon_list_nYq7Fx"
        ],
...

As can be seen from the extract above, which is taken from the theme’s settings_data.json file, the image (shopify://shop_images/icon-shipping.svg) and link (shopify://pages/delivery-information) are now stored as values in the theme.

How to demonstrate the problem

It’s easy to recreate the issue, all we need to do is change the JSON data in the header.liquid template’s schema so that the values stored in the settings_data.json are not no longer valid (e.g. they don’t correspond to anything therefore Shopify doesn’t know what to do with them). For simplicity, I’ll just remove the blocks section from the header.liquid template.

{% schema %}
{
  "name": {
    ...
    "en": "Header",
    ...
  },
  "class": "header-section",
  "settings": [
    ...
  ],
  ...
}
{% endschema %}

This will now introduce the issue and the dreaded “Grey screen of death” will appear instead of the theme’s visual editor:

How to fix the issue and load the visual theme editor once again

Now we’ve reversed-engineered the problem, we can easily solve it. How? We resync them in one of two ways:

We put the data back in the JSON schema section of the header.liquid file, or;
We remove the data that Shopify generated and stored in settings_data.json

Option 2: remove the data that Shopify generated and stored in settings_data.json

This is easy, BUT BE CAREFUL! We identify the block of data and simply delete it. Job done and the theme’s editor will be back in play!

...
    "sections": {
      "header": {
        "type": "header",
...

Need help with this?

I wrote this post to help others so that they don’t have to go through the pain that I had to, in order to resolve this issue. However, if you’re feeling lazy, feel free to reach out for our help. We build Shopify themes, so we have a pretty good understanding of how the platform works.

Get in touch