Truly theme developer docs Guides Reference (format 1)

The check report

Every upload is checked before it becomes a version. The report lists each problem with:

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

  1. The archive: a readable zip without links, encryption, nested archives, Zip64 or oversized files.
  2. The entries: only the files the format allows, the required files present, text files valid UTF-8.
  3. manifest.json and the locale files.
  4. Each Liquid file parses with the tags and filters themes can use; each render names 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.
  5. 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 places membership_pause before membership_termination is 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 inside membership_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.
  6. English strings missing (warnings).
  7. Images, fonts and the stylesheet: images are re-encoded, fonts checked, and assets/theme.css rebuilt. A CSS rule, selector or declaration that is not allowed is left out with a css_* warning; the stylesheet still builds.
  8. 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_states lists 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.