---
title: Referência de erros de build
description: "Todos os códigos de erro de build, com causa raiz e correção: configuração, sintaxe MDX, OpenAPI, tempos limite e problemas de assets."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

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](/pt/components/overview) 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](/pt/help/faq) problemas comuns
3. [Entre em contato com o suporte](/pt/help/support/contact) informando o ID do seu projeto e os detalhes do erro

## Artigos relacionados

<Columns cols={2}>
  <Card title="Falhas de build" icon="triangle-exclamation" href="/pt/help/troubleshooting/build-failures">
    Falhas de build comuns e suas soluções
  </Card>
  <Card title="Contatar o suporte" icon="headset" href="/pt/help/support/contact">
    Obtenha ajuda da nossa equipe
  </Card>
</Columns>