# Problemas comunes

Los errores que muestra la revisión del tema, qué quieren decir y cómo
corregirlos, más las dudas que más aparecen. Cada error viene con el archivo,
la línea y un código, como `html_event_handler`.

> [!TIP]
> Con la IA conectada, pega el mensaje de error y pide: *"Corrige este error
> del tema."* Lee la línea y la ajusta siguiendo las reglas.

## Errores de HTML

El tema no ejecuta JavaScript en la página. Todo lo que ejecuta código se
rechaza.

| Código | Qué pasó | Cómo corregir |
|---|---|---|
| `html_script` | una etiqueta `<script>` | Usa los atributos `data-hystore-*` o una [app aislada](/es/code-theme/apps/) |
| `html_event_handler` | un atributo `onclick`, `onload`... | Cámbialo por la pieza interactiva de la tienda (mira la [guía](/es/code-theme/guide/#piezas-interactivas)) |
| `html_script_url` | un enlace `javascript:`, `vbscript:` o `data:` que no es imagen | Apunta a una página (`/loja`) o usa `data-hystore-open` |
| `html_style` | una etiqueta `<style>` | Pon el CSS en `styles/<nombre>.css` |
| `html_style_attr` | CSS peligroso en `style=""` (`expression`, `behavior`, `javascript:`, `@import`) | Usa CSS normal en un archivo de `styles/` |
| `html_iframe` | `<iframe>` o `<frame>` | Para video, `<hystore-video data-youtube="...">`; para Discord, el bloque `discord` |
| `html_form` | `<form>`, `<input>`, `<select>`... | Los formularios son de la tienda; para búsqueda usa `<hystore-search>` |
| `html_embed` | `<object>`, `<embed>`, `<base>`, `<meta>`, `<link>` | Quítalo; fuentes y estilos entran por `styles/` y `assets/` |
| `html_svg_foreign` | `<foreignObject>` dentro de un SVG | Dibuja solo con SVG |
| `html_ping` | atributo `ping` en un enlace | Quita el atributo |
| `html_entity_trick` | una entidad numérica como `&#106;` | Escribe el carácter directo |
| `html_srcdoc`, `html_http_equiv` | atributos `srcdoc` o `http-equiv` | Quita el atributo |

## Errores de CSS

| Código | Qué pasó | Cómo corregir |
|---|---|---|
| `css_url` | `url()` hacia fuera del tema | Sube la imagen a `assets/` y usa `url(assets/nombre.webp)`; las fuentes de Google en `fonts.gstatic.com` también valen |
| `css_import` | `@import` | Cada archivo de `styles/` ya se carga; fuentes con `@font-face` |
| `css_escape` | una barra invertida fuera de texto entre comillas | Escribe el valor sin escapar, o entre comillas |
| `css_expression`, `css_binding`, `css_script_url` | recursos antiguos que ejecutan código | Quítalos; no hay equivalente seguro |
| `css_image_set` | `image-set()` | Usa `url()` con una imagen del tema |
| `css_at_rule` | `@namespace` o `@document` | Quítalo |
| `css_reserved` | el selector apunta al área obligatoria de la tienda | Esa área (anuncios y enlaces legales) no se puede estilizar |

## Errores de Liquid, secciones y JSON

| Código | Qué pasó | Cómo corregir |
|---|---|---|
| `liquid_syntax` | Liquid mal cerrado o una etiqueta que no existe | Revisa `{% if %}...{% endif %}`, `{% for %}...{% endfor %}` y el nombre de la etiqueta |
| `load_unknown` | `{% load %}` de un dato que no existe | Mira la lista en [Datos](/es/code-theme/guide/#datos) |
| `block_unknown` | `{% hystore_block %}` con un nombre que no existe | Mira [Bloques listos](/es/code-theme/guide/#bloques-listos) |
| `name_not_literal` | `{% render %}`, `{% section %}` o `{% hystore_block %}` sin el nombre entre comillas | Escribe el nombre entre comillas: `{% render 'card' %}` |
| `reference_missing` | el tema usa un componente, sección o app que no existe | Crea el archivo o corrige el nombre |
| `asset_missing` (aviso) | `asset_url` o `url(assets/...)` de una imagen que no se subió | Sube la imagen a `assets/` |
| `schema_place`, `schema_twice` | `{% schema %}` fuera de `sections/`, o dos | Un schema por sección, solo en `sections/` |
| `schema_settings`, `schema_setting_id`, `schema_setting_type`, `schema_setting_duplicate` | un campo del schema inválido | `id` en minúsculas y único; `type` de la [lista de tipos](/es/code-theme/guide/#theme-json) |
| `json_invalid` | JSON roto | Revisa comas y comillas; JSON no acepta comentarios ni coma al final |
| `template_section`, `template_order`, `template_shape` | `templates/<página>.json` apunta a una sección que no existe o está fuera de formato | Mira el formato en [Secciones](/es/code-theme/guide/#secciones) |
| `locale_shape`, `values_shape` | `locales/*.json` o `config/values.json` fuera de formato | Textos en objetos anidados; valores en `{ "settings": {...} }` |
| `locale_missing` (aviso) | falta `en.json` o `es.json` | Crea el archivo; mientras tanto aparece el portugués |

## Errores de archivos y límites

| Código | Qué pasó | Cómo corregir |
|---|---|---|
| `path_invalid` | ruta fuera de las carpetas del tema o con mayúsculas | Mira la [carpeta](/es/code-theme/guide/#carpeta): minúsculas, números, `-` y `_` |
| `file_missing` | falta `theme.json`, `layout/theme.liquid` o `pages/home.liquid` | Crea el archivo (el tema Base tiene los tres) |
| `file_too_big`, `too_many_files`, `theme_too_big` | más de 256 KB por archivo, 400 archivos o 5 MB | Divide el archivo o quita lo que no usas |
| `content_binary` | un archivo de texto con contenido binario | Las imágenes y fuentes van en `assets/` |
| `app_index_missing`, `app_too_big`, `app_too_many_files`, `too_many_apps` | una app sin `index.html`, o con más de 512 KB, 20 archivos o 10 apps | Mira [Apps aisladas](/es/code-theme/apps/#reglas-y-limites) |
| `app_external_script`, `app_external_style`, `app_frame`, `app_form` | una app carga algo de afuera, usa un marco o un formulario | Usa solo los archivos de la propia app y `/sdk/v1.js` |

## Dudas frecuentes

### Cambié el tema y la tienda no cambió

Toda edición va al **borrador**. Publica (o aprueba el pedido de publicación) y
revisa en Tema en código > En la tienda que **Usar el tema en la tienda** esté
encendido.

### La página quedó con el aspecto estándar de la tienda

Dos causas: la página no existe en el tema (por ejemplo, falta
`pages/news.liquid`), o el tema falló al dibujar esa página (un bucle enorme,
un dato que no llegó). En ese caso la tienda cae en el diseño estándar en vez
de quedar en blanco. Mira la vista previa y revisa el tema.

### El carrito, el pago o el perfil no usan mi tema

Es a propósito. Las páginas de dinero y de cuenta son siempre de la tienda,
para que nadie cambie un precio o un botón de pago. Apunta los enlaces a
`/carrinho`, `/perfil` y `/entrar`.

### ¿Puedo usar JavaScript?

En la página, no. Para ruleta, quiz, calculadora o mini juego, usa una
[app aislada](/es/code-theme/apps/): corre en un marco en otro dominio, con un
puente al catálogo y al carrito.

### ¿Puedo cargar una fuente de Google?

Sí: descarga el archivo `.woff2` y súbelo a `assets/`, o usa la dirección
`https://fonts.gstatic.com/...` directo en el `@font-face`. El `@import` del
CSS no se acepta.

### Dos personas editaron el mismo archivo

La segunda escritura se rechaza con `409` en vez de borrar la primera. En el
editor, eliges entre la versión guardada y la tuya; con la herramienta,
`theme pull` junta lo que puede y deja la copia de la tienda como `.remote`.

### Publiqué una versión con un problema

En Tema en código > **Versiones publicadas**, trae una versión anterior al
borrador y publica de nuevo. Las últimas 30 quedan guardadas.

### Quiero quitarle el acceso a una herramienta o IA

**Personalización > Acceso al tema**: revoca la llave o haz clic en
**Desconectar** en la sesión. El acceso se corta al instante.

### Una respuesta de la API vino con 429

Pasaste de 120 lecturas o 30 escrituras por minuto. Espera los segundos del
encabezado `Retry-After` e intenta de nuevo.