Jamdesk Documentation logo

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:

  1. Execute jamdesk validate localmente para ver os erros detalhados
  2. Verifique se há vírgulas, colchetes ou aspas faltando
  3. 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:

  1. Verifique se o arquivo existe no caminho especificado
  2. Confirme que o caminho em docs.json corresponde ao nome real do arquivo (sem .mdx)
  3. 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:

  1. Certifique-se de que o frontmatter começa e termina com ---
  2. Verifique se há erros de sintaxe YAML (dois-pontos faltando, 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 do MDX"

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

Correção:

  1. Certifique-se de que todas as tags JSX estão fechadas corretamente (<Card>...</Card>)
  2. Verifique se as props usam a sintaxe correta (title="valor" e não title=valor)
  3. 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:

  1. Consulte a referência de componentes para os nomes corretos
  2. Os componentes diferenciam maiúsculas de minúsculas: use <Card> e não <card>
  3. 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:

  1. Consulte a documentação do componente para ver as props válidas
  2. Remova as props não suportadas
  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 tem sintaxe ou estrutura inválidas.

Correção:

  1. Execute jamdesk openapi-check para validar localmente
  2. Use um validador 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. Verifique se todos os caminhos $ref estão corretos
  2. Confirme que os schemas referenciados existem em components/schemas
  3. Se um $ref aponta 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:

  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 estiver extremamente grande
  4. 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:

  1. Verifique se o arquivo existe no caminho especificado
  2. Confirme que o caminho é relativo ao diretório da sua documentação
  3. 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:

  1. Comprima imagens com ferramentas como TinyPNG ou ImageOptim
  2. Use formatos adequados (WebP para fotos, SVG para ícones)
  3. Hospede arquivos muito grandes externamente

Como obter ajuda

Se você não conseguir resolver um erro:

  1. Consulte o log completo do build no seu painel para mais contexto
  2. Pesquise nas perguntas frequentes por problemas comuns
  3. Entre em contato com o suporte informando seu ID de projeto e os detalhes do erro

Artigos relacionados

Falhas de build

Falhas comuns de build e soluções

Contatar o suporte

Obtenha ajuda da nossa equipe