Common problems
The errors the theme check shows, what they mean and how to fix them, plus the
questions that come up the most. Each error comes with the file, the line and
a code, such as html_event_handler.
HTML errors
The theme runs no JavaScript on the page. Anything that runs code is refused.
| Code | What happened | How to fix |
|---|---|---|
html_script |
a <script> tag |
Use the data-hystore-* attributes or an isolated app |
html_event_handler |
an onclick, onload... attribute |
Use the store's interactive piece (see the guide) |
html_script_url |
a javascript:, vbscript: or non-image data: link |
Point to a page (/loja) or use data-hystore-open |
html_style |
a <style> tag |
Put the CSS in styles/<name>.css |
html_style_attr |
dangerous CSS in style="" (expression, behavior, javascript:, @import) |
Use normal CSS in a file in styles/ |
html_iframe |
<iframe> or <frame> |
For video, <hystore-video data-youtube="...">; for Discord, the discord block |
html_form |
<form>, <input>, <select>... |
Forms belong to the store; for search use <hystore-search> |
html_embed |
<object>, <embed>, <base>, <meta>, <link> |
Remove it; fonts and styles come through styles/ and assets/ |
html_svg_foreign |
<foreignObject> inside an SVG |
Draw with SVG only |
html_ping |
a ping attribute on a link |
Remove the attribute |
html_entity_trick |
a numeric entity such as j |
Write the character itself |
html_srcdoc, html_http_equiv |
srcdoc or http-equiv attributes |
Remove the attribute |
CSS errors
| Code | What happened | How to fix |
|---|---|---|
css_url |
url() outside the theme |
Upload the image to assets/ and use url(assets/name.webp); Google fonts on fonts.gstatic.com also work |
css_import |
@import |
Every file in styles/ is already loaded; fonts with @font-face |
css_escape |
a backslash outside quoted text | Write the value without escaping, or inside quotes |
css_expression, css_binding, css_script_url |
old features that run code | Remove them; there is no safe equivalent |
css_image_set |
image-set() |
Use url() with a theme image |
css_at_rule |
@namespace or @document |
Remove it |
css_reserved |
the selector targets the store's required area | That area (ads and legal links) cannot be styled |
Liquid, section and JSON errors
| Code | What happened | How to fix |
|---|---|---|
liquid_syntax |
unclosed Liquid or a tag that does not exist | Check {% if %}...{% endif %}, {% for %}...{% endfor %} and the tag name |
load_unknown |
{% load %} of data that does not exist |
See the list in Data |
block_unknown |
{% hystore_block %} with a name that does not exist |
See Ready-made blocks |
name_not_literal |
{% render %}, {% section %} or {% hystore_block %} without the name in quotes |
Write the name in quotes: {% render 'card' %} |
reference_missing |
the theme uses a component, section or app that does not exist | Create the file or fix the name |
asset_missing (warning) |
asset_url or url(assets/...) for an image that was not uploaded |
Upload the image to assets/ |
schema_place, schema_twice |
{% schema %} outside sections/, or two of them |
One schema per section, only in sections/ |
schema_settings, schema_setting_id, schema_setting_type, schema_setting_duplicate |
an invalid schema field | id lowercase and unique; type from the list of types |
json_invalid |
broken JSON | Check commas and quotes; JSON takes no comments and no trailing comma |
template_section, template_order, template_shape |
templates/<page>.json points to a section that does not exist or is out of shape |
See the format in Sections |
locale_shape, values_shape |
locales/*.json or config/values.json out of shape |
Texts in nested objects; values in { "settings": {...} } |
locale_missing (warning) |
en.json or es.json missing |
Create the file; until then, Portuguese shows |
File and limit errors
| Code | What happened | How to fix |
|---|---|---|
path_invalid |
a path outside the theme folders or with capitals | See the folder: lowercase, numbers, - and _ |
file_missing |
theme.json, layout/theme.liquid or pages/home.liquid is missing |
Create the file (the Base theme has all three) |
file_too_big, too_many_files, theme_too_big |
over 256 KB per file, 400 files or 5 MB | Split the file or remove what you do not use |
content_binary |
a text file with binary content | Images and fonts go in assets/ |
app_index_missing, app_too_big, app_too_many_files, too_many_apps |
an app without index.html, or over 512 KB, 20 files or 10 apps |
See Isolated apps |
app_external_script, app_external_style, app_frame, app_form |
an app loads something from outside, uses a frame or a form | Use only the app's own files and /sdk/v1.js |
Frequent questions
I changed the theme and the store did not change
Every edit goes to the draft. Publish (or approve the publish request) and check in Code theme > In the store that Use the theme in the store is on.
The page shows the store's default look
Two causes: the page does not exist in the theme (for example, there is no
pages/news.liquid), or the theme failed to draw that page (a huge loop, data
that did not arrive). In that case the store falls back to the default layout
instead of going blank. Look at the preview and check the theme.
The cart, payment or profile do not use my theme
On purpose. Money and account pages always belong to the store, so nobody can
change a price or a payment button. Point the links to /carrinho, /perfil
and /entrar.
Can I use JavaScript?
Not on the page. For a wheel, quiz, calculator or mini game, use an isolated app: it runs in a frame on another domain, with a bridge to the catalog and the cart.
Can I load a Google font?
Yes: download the .woff2 file and upload it to assets/, or use the
https://fonts.gstatic.com/... address directly in @font-face. The CSS
@import is not accepted.
Two people edited the same file
The second write is refused with 409 instead of erasing the first. In the
editor, you choose between the saved version and yours; with the tool,
theme pull merges what it can and leaves the store's copy as .remote.
I published a version with a problem
In Code theme > Published versions, bring an earlier version back to the draft and publish again. The last 30 are kept.
I want to remove a tool's or an AI's access
Customization > Theme access: revoke the key or click Disconnect on the session. The access stops at once.
An API answer came with 429
You went over 120 reads or 30 writes per minute. Wait the seconds in the
Retry-After header and try again.
