# Problemas comuns

Os erros que a conferência do tema mostra, o que eles querem dizer e como
corrigir, mais as dúvidas que mais aparecem. Cada erro vem com o arquivo, a
linha e um código, como `html_event_handler`.

> [!TIP]
> Com a IA conectada, cole a mensagem de erro e peça: *"Corrige esse erro do
> tema."* Ela lê a linha e ajusta seguindo as regras.

## Erros de HTML

O tema não roda JavaScript na página. Tudo que executa código é recusado.

| Código | O que houve | Como corrigir |
|---|---|---|
| `html_script` | uma tag `<script>` | Use os atributos `data-hystore-*` ou um [app isolado](/pt/code-theme/apps/) |
| `html_event_handler` | um atributo `onclick`, `onload`... | Troque pela peça interativa da loja (veja o [guia](/pt/code-theme/guide/#pecas-interativas)) |
| `html_script_url` | link `javascript:`, `vbscript:` ou `data:` que não é imagem | Aponte para uma página (`/loja`) ou use `data-hystore-open` |
| `html_style` | uma tag `<style>` | Ponha o CSS em `styles/<nome>.css` |
| `html_style_attr` | CSS perigoso em `style=""` (`expression`, `behavior`, `javascript:`, `@import`) | Use CSS normal num arquivo de `styles/` |
| `html_iframe` | `<iframe>` ou `<frame>` | Para vídeo, `<hystore-video data-youtube="...">`; para Discord, o bloco `discord` |
| `html_form` | `<form>`, `<input>`, `<select>`... | Formulários são da loja; para busca use `<hystore-search>` |
| `html_embed` | `<object>`, `<embed>`, `<base>`, `<meta>`, `<link>` | Tire; fontes e estilos entram por `styles/` e `assets/` |
| `html_svg_foreign` | `<foreignObject>` dentro de um SVG | Desenhe só com SVG |
| `html_ping` | atributo `ping` em link | Tire o atributo |
| `html_entity_trick` | entidade numérica como `&#106;` | Escreva o caractere direto |
| `html_srcdoc`, `html_http_equiv` | atributos `srcdoc` ou `http-equiv` | Tire o atributo |

## Erros de CSS

| Código | O que houve | Como corrigir |
|---|---|---|
| `css_url` | `url()` para fora do tema | Envie a imagem para `assets/` e use `url(assets/nome.webp)`; fontes do Google em `fonts.gstatic.com` também valem |
| `css_import` | `@import` | Cada arquivo de `styles/` já é carregado; fontes com `@font-face` |
| `css_escape` | barra invertida fora de texto entre aspas | Escreva o valor sem escapar, ou dentro de aspas |
| `css_expression`, `css_binding`, `css_script_url` | recursos antigos que executam código | Tire; não existe equivalente seguro |
| `css_image_set` | `image-set()` | Use `url()` com uma imagem do tema |
| `css_at_rule` | `@namespace` ou `@document` | Tire |
| `css_reserved` | o seletor mira a área obrigatória da loja | Essa área (anúncios e links legais) não pode ser estilizada |

## Erros de Liquid, seções e JSON

| Código | O que houve | Como corrigir |
|---|---|---|
| `liquid_syntax` | Liquid mal fechado ou tag que não existe | Confira `{% if %}...{% endif %}`, `{% for %}...{% endfor %}` e o nome da tag |
| `load_unknown` | `{% load %}` de um dado que não existe | Veja a lista em [Dados](/pt/code-theme/guide/#dados) |
| `block_unknown` | `{% hystore_block %}` com nome que não existe | Veja [Blocos prontos](/pt/code-theme/guide/#blocos-prontos) |
| `name_not_literal` | `{% render %}`, `{% section %}` ou `{% hystore_block %}` sem o nome entre aspas | Escreva o nome entre aspas: `{% render 'card' %}` |
| `reference_missing` | o tema usa um componente, seção ou app que não existe | Crie o arquivo ou corrija o nome |
| `asset_missing` (aviso) | `asset_url` ou `url(assets/...)` para uma imagem que não foi enviada | Envie a imagem para `assets/` |
| `schema_place`, `schema_twice` | `{% schema %}` fora de `sections/`, ou dois | Um schema por seção, só em `sections/` |
| `schema_settings`, `schema_setting_id`, `schema_setting_type`, `schema_setting_duplicate` | campo do schema inválido | `id` em minúsculas e único; `type` da [lista de tipos](/pt/code-theme/guide/#theme-json) |
| `json_invalid` | JSON quebrado | Confira vírgulas e aspas; JSON não aceita comentário nem vírgula no fim |
| `template_section`, `template_order`, `template_shape` | `templates/<página>.json` aponta para seção que não existe ou está fora do formato | Veja o formato em [Seções](/pt/code-theme/guide/#secoes) |
| `locale_shape`, `values_shape` | `locales/*.json` ou `config/values.json` fora do formato | Textos em objetos aninhados; valores em `{ "settings": {...} }` |
| `locale_missing` (aviso) | falta `en.json` ou `es.json` | Crie o arquivo; até lá, aparece o português |

## Erros de arquivos e limites

| Código | O que houve | Como corrigir |
|---|---|---|
| `path_invalid` | caminho fora das pastas do tema ou com maiúsculas | Veja a [pasta](/pt/code-theme/guide/#pasta): minúsculas, números, `-` e `_` |
| `file_missing` | falta `theme.json`, `layout/theme.liquid` ou `pages/home.liquid` | Crie o arquivo (o tema Base tem os três) |
| `file_too_big`, `too_many_files`, `theme_too_big` | passou de 256 KB por arquivo, 400 arquivos ou 5 MB | Divida o arquivo ou tire o que não usa |
| `content_binary` | arquivo de texto com conteúdo binário | Imagens e fontes vão em `assets/` |
| `app_index_missing`, `app_too_big`, `app_too_many_files`, `too_many_apps` | um app sem `index.html`, ou acima de 512 KB, 20 arquivos ou 10 apps | Veja [Apps isolados](/pt/code-theme/apps/#regras-e-limites) |
| `app_external_script`, `app_external_style`, `app_frame`, `app_form` | um app carrega coisa de fora, usa quadro ou formulário | Use só arquivos do próprio app e o `/sdk/v1.js` |

## Dúvidas frequentes

### Mudei o tema e a loja não mudou

Toda edição vai para o **rascunho**. Publique (ou aprove o pedido de
publicação) e confira em Tema em código > Na loja se **Usar o tema na loja**
está ligado.

### A página ficou com o visual padrão da loja

Duas causas: a página não existe no tema (por exemplo, falta
`pages/news.liquid`), ou o tema falhou ao desenhar aquela página (um laço
gigante, um dado que não chegou). Nesse caso a loja cai no layout padrão em vez
de ficar em branco. Veja a prévia e confira o tema.

### O carrinho, o pagamento ou o perfil não usam o meu tema

É de propósito. Páginas de dinheiro e de conta são sempre da loja, para
ninguém trocar um preço ou um botão de pagamento. Aponte os links para
`/carrinho`, `/perfil` e `/entrar`.

### Posso usar JavaScript?

Na página, não. Para roleta, quiz, calculadora ou mini jogo, use um
[app isolado](/pt/code-theme/apps/): ele roda num quadro em outro domínio, com
uma ponte para o catálogo e o carrinho.

### Posso carregar uma fonte do Google?

Pode: baixe o arquivo `.woff2` e envie para `assets/`, ou use o endereço
`https://fonts.gstatic.com/...` direto no `@font-face`. O `@import` do CSS não
é aceito.

### Duas pessoas editaram o mesmo arquivo

A segunda gravação é recusada com `409` em vez de apagar a primeira. No editor,
você escolhe entre a versão salva e a sua; na ferramenta, `theme pull` junta o
que dá e deixa a cópia da loja como `.remote`.

### Publiquei uma versão com problema

Em Tema em código > **Versões publicadas**, traga uma versão anterior para o
rascunho e publique de novo. As últimas 30 ficam guardadas.

### Quero tirar o acesso de uma ferramenta ou IA

**Personalização > Acesso ao tema**: revogue a chave ou clique em
**Desconectar** na sessão. O acesso para na hora.

### Uma resposta da API veio com 429

Passou de 120 leituras ou 30 gravações por minuto. Espere os segundos do
cabeçalho `Retry-After` e tente de novo.