The check report
Every upload is checked before it becomes a version. The report lists each problem with:
- its level: an error blocks the version; a warning is kept on it and the version is still made; a
Testedline lists the states each template was rendered in; - its reason, a fixed code (the package format reference lists them all);
- the file in the package, the Liquid line where known, and for locale strings the key.
The report never quotes your template's text or a Liquid error message, apart from the name of an element or attribute themes cannot use (<script>, <p onclick>).
The order of the checks
- The archive: a readable zip without links, encryption, nested archives, Zip64 or oversized files.
- The entries: only the files the format allows, the required files present, text files valid UTF-8.
manifest.jsonand the locale files.- Each Liquid file parses with the tags and filters themes can use; each
rendernames a snippet in the package; each template's name is a known route; the layout prints{{ content_for_layout }}once and places the footer slot at its top level. - The slot rules: a template whose page, together with the layout and the snippets they render, never places a slot that every state requires is an error (
missing_slot, with the slot as the key); a slot only some states require and placed nowhere is a warning (missing_state_slot); a page that placesmembership_pausebeforemembership_terminationis an error (slot_order), since pausing is offered only after cancelling. A slot written in the template outside the container slot it belongs to (the legal parts inside the checkout pages' containers, the membership actions insidemembership_status), or a container inside one that is not its own, is an error (slot_container); a slot placed by a snippet is checked when the page renders. - English strings missing (warnings).
- Images, fonts and the stylesheet: images are re-encoded, fonts checked, and
assets/theme.cssrebuilt. A CSS rule, selector or declaration that is not allowed is left out with acss_*warning; the stylesheet still builds. - Sample renders: each template is rendered, with the layout and its snippets, in every state of its route (routes) and in both languages, with sample data in place of the tenant's, through the same renderer and slot rules as a live page. A state that fails is an error,
fixture_render, whose key is the state and the render's reason (empty: undefined,pay: slot_unknown);fixture_stateslists the states each template passed. This needs no custom domain.
Steps 1 and 2 stop the check at their first problems; steps 3 and 4 report all their problems together; the slot rules run only when nothing else is an error, and images, fonts, the stylesheet and the sample renders only when there is no error at all. So a fixed package can show new problems from a later step: upload again until it passes.
Common problems
| Reason | Usually means |
|---|---|
unexpected_entry |
A file outside the format, often .DS_Store, README.md or the folder itself zipped as the top entry. Zip the folder's contents. |
missing_slot |
The page can never show: place the slot in the template, the layout or a snippet they render. |
footer_slot, content_for_layout |
The footer slot or {{ content_for_layout }} sits inside an if or for, in a snippet, or is missing. |
liquid_syntax |
A Liquid mistake on that line, or a tag or filter themes cannot use (include, increment). |
unknown_route |
A template named after a page Truly does not have: check the routes. |
image_svg |
SVG is not accepted; export the image as PNG, JPEG or WebP. |
format_version |
The manifest declares another format than the current one. |
fixture_render |
The template fails in that state: a variable the route does not have (undefined), or a slot the state does not allow or requires and the template leaves out (slot_unknown, slot_count). Branch on the state fields to place a slot only where the state needs it. An element or attribute themes cannot use (tag, attribute, foreign) is named, with the first line of the template, layout or snippet that writes it; when no file writes it as such (it is put together while the template renders), the line is the rendered HTML's and the report says so. |
After upload
The check renders with sample data only, never the tenant's. A template can still fail on a live page, for example on a value the sample data does not have: that page then falls back to the default theme, and the failure is counted per version and day with its reason, template and line, which the tenant can share with you.