Solução de problemas de build
Resolva falhas comuns de build associando mensagens de erro às causas e soluções. Cobre erros de configuração, dependências ausentes, sintaxe MDX e problemas com ícones.
O log de build mostra o que quebrou e onde. Encontre sua mensagem de erro abaixo.
Visualizar detalhes do erro
- Abra a aba Deployments do seu projeto
- Clique no build com falha
- Leia a mensagem de erro e role pelo log de build
O log aponta o arquivo e a linha exatos que interromperam o build.
Erros comuns
Erros de configuração
Invalid docs.json significa que seu arquivo de configuração não pode ser analisado. A causa mais comum é uma vírgula sobrando, um colchete não fechado ou uma aspa ausente.
Procure por vírgulas, colchetes ou aspas ausentes.
Execute jamdesk validate para ver os erros exatos.
Corrija-os e envie para acionar um novo build.
Páginas ausentes
Page not found significa que sua navegação aponta para um arquivo que não existe. Compare o nome do arquivo com o caminho em docs.json. A diferença entre maiúsculas e minúsculas deve ser exata. Não inclua a extensão .mdx.
Erros de sintaxe MDX
MDX compilation failed aponta para MDX ou JSX malformado em uma página. Geralmente é uma tag não fechada (um <Card> sem o </Card> correspondente), um caractere não escapado, como um { literal onde você queria \{, ou sintaxe de prop inválida.
Tempo limite do build
Build exceeded time limit significa que o build excedeu o tempo permitido. Imagens grandes e não otimizadas são a causa mais comum. Comprima-as, divida páginas muito grandes e remova páginas que você não publica mais.
Avisos do build
Avisos nunca fazem um build falhar. Seu site continua sendo publicado. Os avisos aparecem no e-mail de avisos de build, na entrada do build na aba Deployments e no terminal quando você executa jamdesk validate ou jamdesk dev.
Imagens ausentes
Image not found avisa que uma página referencia uma imagem que seu projeto não contém.
O Jamdesk verifica cada referência de imagem (Markdown  e também o src nas tags <img loading="lazy"> e <Image>) contra os arquivos do seu repositório. O aviso indica a página, o número da linha e o caminho que não pôde ser resolvido.
Envie a imagem ou aponte o caminho para um arquivo existente. Caminhos diferenciam maiúsculas de minúsculas. Um caminho com / inicial é resolvido a partir da raiz do projeto. Qualquer outro caminho é resolvido em relação à página. Uma referência a photo.png continua funcionando depois que a otimização de imagens a converte para WebP.
O Jamdesk ignora URLs externas, URIs data: e sintaxe de imagem dentro de blocos de código.
Etapas de depuração
O log indica o arquivo e a linha exatos por trás do erro. Comece por aí.
Execute jamdesk dev para reproduzir a falha localmente.
Execute jamdesk validate para verificar docs.json. Execute jamdesk broken-links para encontrar links internos quebrados.
Analise seu último commit. Você adicionou uma página ou alterou a configuração?
Ainda com problemas?
Se nada do que foi descrito acima resolver:
- Copie o log de build completo
- Anote o ID do seu projeto (ele está na URL)
- Entre em contato com o suporte
