Referência de erros de build

Encontre seu código de erro com Ctrl/Cmd+F ou navegue por categoria: configuração, MDX, OpenAPI, tempos limite e assets.

Erros de configuração

INVALID_DOCS_JSON

Mensagem: "Configuração inválida de docs.json"

Causa: Seu arquivo docs.json contém erros de sintaxe ou valores inválidos.

Correção:

1. Execute jamdesk validate localmente para ver os erros detalhados
2. Verifique se há vírgulas, colchetes ou aspas ausentes
3. Confirme se todos os valores correspondem ao schema esperado

MISSING_PAGE

Mensagem: "A página 'path/to/page' foi referenciada na navegação, mas o arquivo não foi encontrado"

Causa: Uma página listada na navegação de docs.json não existe.

Correção:

1. Verifique se o arquivo existe no caminho especificado
2. Confirme se o caminho em docs.json corresponde ao nome de arquivo real (sem .mdx)
3. Os caminhos diferenciam maiúsculas de minúsculas, portanto verifique a capitalização

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:

1. Confirme se o frontmatter começa e termina com ---
2. Verifique se há sintaxe YAML inválida (dois-pontos ausentes ou indentação incorreta)
3. Coloque entre aspas as strings que contêm caracteres especiais

Erros de MDX

MDX_SYNTAX_ERROR

Mensagem: "Falha na compilação de MDX"

Causa: Sintaxe MDX ou JSX inválida no seu conteúdo.

Correção:

1. Confirme se todas as tags JSX estão fechadas corretamente (<Card>...</Card>)
2. Verifique se as props usam a sintaxe correta (title="value", não title=value)
3. Escape as chaves no texto comum: \{ em vez de {

COMPONENT_NOT_FOUND

Mensagem: "Componente desconhecido 'ComponentName'"

Causa: Você está usando um componente que não existe no Jamdesk.

Correção:

1. Consulte a referência de componentes para conferir os nomes corretos
2. Os componentes diferenciam maiúsculas de minúsculas: use <Card>, não <card>
3. Confirme se você não está importando componentes personalizados (não compatível)

INVALID_PROPS

Mensagem: "Props inválidas para o componente 'ComponentName'"

Causa: Um componente recebeu props que não aceita.

Correção:

1. Consulte a documentação do componente para verificar as props válidas
2. Remova as props não compatíveis
3. Verifique o tipo esperado da prop na documentação do componente (por exemplo, cols espera 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 contém sintaxe ou estrutura inválida.

Correção:

1. Execute jamdesk openapi-check localmente para validar
2. Use um validador de OpenAPI, como o Swagger Editor
3. 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:

1. Confirme se todos os caminhos de $ref estão corretos
2. Verifique se os schemas referenciados existem em components/schemas
3. Se um $ref apontar para um arquivo ou URL externo, confirme se o arquivo está incluído no projeto e se a URL está acessível

Tempo limite do build

BUILD_TIMEOUT

Mensagem: "O build excedeu o tempo limite máximo"

Causa: O build demorou mais que o tempo permitido (geralmente 5 minutos).

Correção:

1. Otimize imagens grandes (comprima ou redimensione)
2. Divida páginas muito grandes em páginas menores
3. Reduza o número de páginas se o projeto for extremamente grande
4. Entre em contato com o suporte se o problema persistir

Erros de assets

ASSET_NOT_FOUND

Mensagem: "O asset 'path/to/asset' não foi encontrado"

Causa: Uma imagem ou um arquivo referenciado na sua documentação não existe.

Correção:

1. Verifique se o arquivo existe no caminho especificado
2. Confirme se o caminho é relativo ao diretório da sua documentação
3. Os caminhos diferenciam maiúsculas de minúsculas, portanto verifique o nome exato do arquivo

ASSET_TOO_LARGE

Mensagem: "O asset excede o tamanho máximo de arquivo"

Causa: Uma imagem ou um arquivo é maior que o limite de 10 MB.

Correção:

1. Comprima as imagens usando ferramentas como TinyPNG ou ImageOptim
2. Use formatos apropriados (WebP para fotos, SVG para ícones)
3. Considere hospedar arquivos muito grandes externamente

Como obter ajuda

Se não conseguir resolver um erro:

1. Verifique o log completo do build no seu dashboard para obter mais contexto
2. Pesquise na FAQ problemas comuns
3. Entre em contato com o suporte informando o ID do seu projeto e os detalhes do erro

Artigos relacionados