Referência de erros de build
Todos os códigos de erro de build com sua causa raiz e correção: configuração, sintaxe MDX, OpenAPI, timeouts e problemas com ativos.
Encontre seu código de erro com Ctrl/Cmd+F ou navegue por categoria: configuração, MDX, OpenAPI, timeouts e ativos.
Erros de configuração
INVALID_DOCS_JSON
Mensagem: "Configuração docs.json inválida"
Causa: Seu arquivo docs.json tem erros de sintaxe ou valores inválidos.
Correção:
- Execute
jamdesk validatelocalmente para ver os erros detalhados - Verifique se há vírgulas, colchetes ou aspas faltando
- Confirme que todos os valores correspondem ao schema esperado
MISSING_PAGE
Mensagem: "Página 'path/to/page' referenciada na navegação, mas o arquivo não foi encontrado"
Causa: Uma página listada na navegação do docs.json não existe.
Correção:
- Verifique se o arquivo existe no caminho especificado
- Confirme que o caminho em
docs.jsoncorresponde ao nome real do arquivo (sem.mdx) - Verifique as maiúsculas e minúsculas. Os caminhos diferenciam maiúsculas de minúsculas
INVALID_FRONTMATTER
Mensagem: "Frontmatter inválido em 'path/to/page'"
Causa: O frontmatter YAML no início de um arquivo MDX está malformado.
Correção:
- Certifique-se de que o frontmatter começa e termina com
--- - Verifique se há erros de sintaxe YAML (dois-pontos faltando, indentação incorreta)
- Coloque entre aspas as strings que contêm caracteres especiais
Erros de MDX
MDX_SYNTAX_ERROR
Mensagem: "Falha na compilação do MDX"
Causa: Sintaxe MDX ou JSX inválida no seu conteúdo.
Correção:
- Certifique-se de que todas as tags JSX estão fechadas corretamente (
<Card>...</Card>) - Verifique se as props usam a sintaxe correta (
title="valor"e nãotitle=valor) - Escape as chaves em texto comum:
\{em vez de{
COMPONENT_NOT_FOUND
Mensagem: "Componente desconhecido 'ComponentName'"
Causa: Uso de um componente que não existe no Jamdesk.
Correção:
- Consulte a referência de componentes para os nomes corretos
- Os componentes diferenciam maiúsculas de minúsculas: use
<Card>e não<card> - Verifique se você não está importando componentes personalizados (não suportado)
INVALID_PROPS
Mensagem: "Props inválidas para o componente 'ComponentName'"
Causa: Um componente recebeu props que ele não aceita.
Correção:
- Consulte a documentação do componente para ver as props válidas
- Remova as props não suportadas
- Verifique o tipo esperado da prop na documentação do componente (por exemplo,
colsespera um número, não uma string)
Erros de OpenAPI
OPENAPI_PARSE_ERROR
Mensagem: "Falha ao analisar a especificação OpenAPI"
Causa: Seu arquivo de especificação OpenAPI tem sintaxe ou estrutura inválidas.
Correção:
- Execute
jamdesk openapi-checkpara validar localmente - Use um validador OpenAPI, como o Swagger Editor
- Verifique se a sintaxe JSON ou YAML é válida
OPENAPI_REFERENCE_ERROR
Mensagem: "Referência não resolvida na especificação OpenAPI"
Causa: Um $ref na sua especificação OpenAPI aponta para uma definição inexistente.
Correção:
- Verifique se todos os caminhos
$refestão corretos - Confirme que os schemas referenciados existem em
components/schemas - Se um
$refaponta para um arquivo externo ou URL, confirme que o arquivo está incluído no seu projeto e que a URL está acessível
Tempo limite do build
BUILD_TIMEOUT
Mensagem: "O build excedeu o tempo máximo permitido"
Causa: O build levou mais tempo do que o permitido (normalmente 5 minutos).
Correção:
- Otimize imagens grandes (comprima ou redimensione)
- Divida páginas muito grandes em páginas menores
- Reduza o número de páginas se estiver extremamente grande
- Entre em contato com o suporte se o problema persistir
Erros de assets
ASSET_NOT_FOUND
Mensagem: "Ativo 'path/to/asset' não encontrado"
Causa: Uma imagem ou arquivo referenciado na sua documentação não existe.
Correção:
- Verifique se o arquivo existe no caminho especificado
- Confirme que o caminho é relativo ao diretório da sua documentação
- Corresponda exatamente as maiúsculas e minúsculas do nome do arquivo. Os caminhos diferenciam maiúsculas de minúsculas
ASSET_TOO_LARGE
Mensagem: "O ativo excede o tamanho máximo de arquivo"
Causa: Uma imagem ou arquivo é maior que o limite de 10 MB.
Correção:
- Comprima imagens com ferramentas como TinyPNG ou ImageOptim
- Use formatos adequados (WebP para fotos, SVG para ícones)
- Hospede arquivos muito grandes externamente
Como obter ajuda
Se você não conseguir resolver um erro:
- Consulte o log completo do build no seu painel para mais contexto
- Pesquise nas perguntas frequentes por problemas comuns
- Entre em contato com o suporte informando seu ID de projeto e os detalhes do erro
