# 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`.

> [!TIP]
> With the AI connected, paste the error message and ask: *"Fix this theme
> error."* It reads the line and adjusts it following the rules.

## 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](/en/code-theme/apps/) |
| `html_event_handler` | an `onclick`, `onload`... attribute | Use the store's interactive piece (see the [guide](/en/code-theme/guide/#interactive-pieces)) |
| `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 `&#106;` | 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](/en/code-theme/guide/#data) |
| `block_unknown` | `{% hystore_block %}` with a name that does not exist | See [Ready-made blocks](/en/code-theme/guide/#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](/en/code-theme/guide/#theme-json) |
| `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](/en/code-theme/guide/#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](/en/code-theme/guide/#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](/en/code-theme/apps/#rules-and-limits) |
| `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](/en/code-theme/apps/): 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.