Troubleshooting

O componente não salva

Confira nesta ordem:

1. O tipo está correto?
2. O nome interno usa snake_case?
3. O schema contém title, description, component_config.settings e component_config.content?
4. Cada tipo de arquivo usado possui exatamente um principal?
5. Há arquivos do mesmo tipo com o mesmo nome?
6. Todo partial ou @import-partial aponta para um auxiliar existente?
7. O JavaScript principal segue o contrato do tipo?

Erros de schema

Situação	Correção
JSON inválido	Revise vírgulas, aspas e chaves.
Campo não aparece	Mova-o para settings, content, settings_mobile ou content_mobile.
Lista sem controles de itens	Use items: [{ ... }].
Lista em settings	Mova-a para content, content_mobile ou preferences.items.
content_limit sem lista	Adicione content.items ou remova o limite.
Conteúdo mobile sem fallback	Faça fallback para o conteúdo desktop no Liquid quando necessário.

Veja Schema.

Erros de arquivos

Situação	Correção
Falta arquivo principal	Adicione um principal para cada tipo de arquivo ativo.
Mais de um principal	Mantenha apenas um principal por tipo.
Nome auxiliar inválido	Use snake_case, sem extensão.
Referência inexistente	Crie o auxiliar ou corrija o nome na referência.
Auxiliar chama principal	Faça o principal chamar auxiliares, nunca o contrário.
Referência circular	Reorganize as chamadas para remover o ciclo.
Token inválido	Use {% partial 'nome' %} ou @import-partial 'nome';.

JavaScript incorreto

• Em top_bar, o principal exporta uma função: export default function setTopBar() {}.
• Nos outros tipos com JavaScript, exporte um objeto com init().
• Um auxiliar JavaScript chamado por @import-partial também exporta um objeto com init().

O componente salvou, mas não aparece

Salvar apenas disponibiliza o componente. Selecione-o pelo título na área correta, configure-o e publique a loja. Para globais, ative-o em Componentes globais.

Não consigo excluir

O retorno 409 indica que o componente ainda está selecionado ou em uma edição pendente. Remova todas as referências antes de excluí-lo. Depois da exclusão ele deixa o catálogo; não há recuperação automática para uma configuração antiga ou inválida.

Não consigo publicar com componente inativo

Identifique o nome do componente informado na falha. Reative-o se ele deve continuar na loja; caso contrário, remova-o da seleção e das edições pendentes. Só então salve e publique novamente.

Problemas em vitrines de produtos

Situação	Correção
A vitrine não exibe produtos	Confira se a tag está preenchida e se há produtos associados a ela. Carregue a lista com {% load_products tag: ... %} antes do loop.
A lista products está vazia ou não existe	Use products somente depois de {% load_products %} e mantenha o loop no mesmo cenário da tag carregada.
O card não segue o Product Block selecionado	Passe component_configs: product_block_config ao renderizar partials/components/product_block.
A seção usa product_block_config como produto	Use um item product do loop. product_block_config contém somente opções do card.
Abas diferentes mostram a mesma coleção	Revise títulos e tags sugeridas. Títulos dinâmicos iguais geram a mesma sugestão de tag.

Veja o exemplo completo em Vitrines de produtos.

Contratos avançados

Leia novamente o guia do tipo se o problema envolver header, footer, product block, botões ou ícones. Esses tipos não aceitam implementações parciais.