Fixing HTML Errors in Shopify Themes

How a Shopify page is put together

Knowing which file produced a line of HTML is most of the work. An Online Store 2.0 theme is organised like this:

Most validator errors on a Shopify store sit in sections, snippets or content. Errors inside the scripts output by content_for_header, or on checkout pages, are outside your control; note them and move on.

Telling the sources apart in the page source

Open the page, view its source and use the line number the validator gives you. Shopify leaves useful clues:

• Section wrappers. Each section is output inside a wrapper with an id like shopify-section-template--1234567890__main and a class such as shopify-section. Scroll up from the error to the nearest wrapper and its name tells you the section file; __main on a product page is usually main-product.liquid.
• App blocks are wrapped with a shopify-block class and an id containing the app's name or handle. An error inside one belongs to the app.
• App embeds usually appear just before the closing </body> tag. Turn them off one at a time under the theme editor's App embeds panel and re-validate to see which one is responsible.
• Legacy app code is harder to spot: older apps edited theme files directly, adding lines such as {% render 'some-app-widget' %} or {% include %} to your templates. Search the code editor for the app's name.
• Content appears inside the description or article body container, usually a div with a class such as rte. Errors there come from the text entered in the admin.

Validate the same template on two different products or articles. If an error appears on both at the same place, it is theme or app code; if it only appears on one, it is that item's content.

Testing a store that is not public yet

If the store is behind a password page, an external checker sees only the password page. Either validate after launch, share a theme preview link, or open the page in your browser, view the source, and paste it into the W3C validator's direct input option. Check that you are testing the duplicated theme, not the live one.

The Liquid mistakes behind most theme errors

Rich text settings inside a paragraph

A section setting of type richtext already outputs its own <p> or list tags. A template that wraps it in another paragraph produces a paragraph inside a paragraph, which the parser splits apart and the validator reports as a stray end tag:

{%- comment -%} Invalid: richtext already outputs <p> {%- endcomment -%}
<p class="banner__text">{{ section.settings.text }}</p>

{%- comment -%} Valid {%- endcomment -%}
<div class="banner__text">{{ section.settings.text }}</div>

For short text that should sit inside a heading or paragraph, use the inline_richtext setting type instead, which allows bold, italic and links but no wrapping paragraph. The same trap applies to {{ product.description }}, {{ article.content }} and rich text metafields: always place them in a div, never a p or span.

Tags opened and closed under different conditions

{%- if card_product.url -%}<a href="{{ card_product.url }}">{%- endif -%}
  {{ card_product.title | escape }}
{%- if show_link -%}</a>{%- endif -%}

If the two conditions ever differ, the page gets an unclosed or stray </a>. Use the same condition for both halves, or better, output the whole element inside one if block with an else for the unlinked version.

Unescaped values inside attributes

Product titles, alt text and metafield values can contain double quotes, such as a 27" monitor. Printed raw inside alt="...", the quote ends the attribute early and the rest becomes junk attributes. Use the escape filter on anything printed inside an attribute: alt="{{ product.title | escape }}". Shopify's image_tag filter builds the image element for you, with width, height and alt handled.

Hard-coded ids in sections that can be added twice

A section added twice to one template, or a product card snippet used in a loop, repeats any fixed id. Build ids from section.id, block.id or the product's id. The duplicate ids guide shows the pattern in Liquid, including the product form and quick-add modal case.

Blocks inside elements that cannot hold them

Theme blocks that output a div placed inside a <p>, <span>, <button> or <a> wrapper create nesting errors. Check the wrapper element in the section around {% for block in section.blocks %}, and use a div when the blocks can contain block-level content.

App code: blocks, embeds and what uninstalling leaves behind

Apps reach your storefront in three ways, and each is handled differently.

1. App blocks are added to sections in the theme editor. If one produces invalid markup, check its settings, update the app, and report the error to the developer. You can remove the block from a template without uninstalling the app.
2. App embeds are switched on and off in the theme editor's App embeds panel. They are removed cleanly when disabled, which makes them easy to test: switch one off, preview, validate.
3. Direct theme edits by older apps, and by developers following an app's manual install steps, add snippets and render or include tags to your theme files. Uninstalling the app does not remove them. The snippet may keep printing an empty container or a broken tag, or the render tag may point at a snippet that no longer exists, which Liquid reports as an error message in the output.

To clean up leftovers, list the apps you have removed, search the code editor for each name, and check the snippets folder for files named after them. Remove the render line and then the snippet file, on the duplicated theme, and preview the affected templates before publishing.

Scripts that apps inject through content_for_header cannot be edited at all. If one outputs invalid markup, report it to the developer and weigh the feature against the problem.

Errors inside product descriptions and pages

Content errors usually come from copying descriptions out of a supplier's website, a spreadsheet, a word processor or another platform during migration. Typical finds are <font> and <center> tags, empty paragraphs, tables with fixed widths, unclosed list items and whole <html> or <body> fragments pasted from a full page.

• Use the editor's HTML view. The rich text editor in the Shopify admin has a button to show HTML. Open it on the affected item and delete the offending tags directly.
• Paste as plain text. When adding new descriptions from other sources, paste without formatting and reapply bold, lists and links using the editor's own buttons.
• Fix in bulk with a CSV. For hundreds of products, export products to CSV, clean the Body (HTML) column with a careful search and replace in a text editor, and re-import a test batch before the rest. Keep the original export as a backup.
• Metafields. Rich text metafields store structured content and are rendered by Shopify, so they rarely contain invalid HTML; errors around them usually come from the template wrapping them in the wrong element, as described above.

For obsolete tags in particular, the deprecated HTML guide lists the modern replacement for each one.

The fix, step by step

Theme updates, customisations and keeping it clean

Code edits and theme updates pull in opposite directions. When your theme developer releases a new version, your changes to its files are not carried across automatically, so fixes made in theme files may need reapplying after an update. A few habits keep that manageable:

• Keep a change log. Record each file you edited and why, or keep the theme in GitHub using Shopify's GitHub integration so every change is a commit you can compare and reapply.
• Prefer settings over code. Use section and block settings, custom CSS fields in the theme editor and app blocks rather than editing theme files, since settings generally survive updates better than code edits.
• Report bugs upstream. If an error is in the theme's own code, tell the theme developer. Fixed at the source, it stays fixed for every future version.
• Be careful with Custom Liquid sections. A Custom Liquid section lets anyone with theme access paste raw code into a template. It is useful, but it is also the easiest way to add unclosed tags. Validate the page every time one is added or changed.
• Re-validate after installing any app. New apps are the most common cause of new errors on an otherwise clean theme.

Accessibility checks on Shopify, such as colour contrast and keyboard access, are covered separately in the Shopify accessibility guide.