---
title: Falhas de build
description: "Associe seu erro de build à solução: falhas de configuração, erros de sintaxe MDX, arquivos ausentes, problemas de OpenAPI e timeouts."
---

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

Abra o build com falha na guia **Deployments** e associe a mensagem de erro à seção correspondente abaixo.

## Encontrar o erro

1. Acesse a guia **Deployments** do seu projeto
2. Clique no build com falha
3. Revise a mensagem de erro e o log

O log mostra exatamente o que deu errado e onde.

## Falhas comuns

### Configuração inválida

**Erro:** "Invalid docs.json"

Seu `docs.json` contém erros de sintaxe ou de esquema.

**Solução:**
1. Verifique se há vírgulas, colchetes ou aspas ausentes
2. Execute `jamdesk validate` localmente
3. Compare com a [referência do esquema](/pt/config/docs-json-reference)

### Páginas ausentes

**Erro:** "Page 'path/to/page' not found"

Uma página da navegação não existe.

**Solução:**
- Verifique se o arquivo existe
- Confirme se o caminho corresponde exatamente (diferencia maiúsculas de minúsculas)
- Não inclua a extensão `.mdx` em `docs.json`

### Erros de sintaxe MDX

**Erro:** "MDX compilation failed"

Sintaxe MDX ou JSX inválida.

**Causas comuns:**
- Tags não fechadas: `<Card>` sem `</Card>`
- Chaves não escapadas: `{` em vez de `\{`
- Props inválidas: `title=value` em vez de `title="value"`

### Imagens ausentes

**Erro:** "Asset not found"

Uma imagem referenciada no MDX não existe.

**Solução:**
- Verifique se o caminho da imagem está correto
- Os caminhos são relativos ao diretório da documentação
- Confirme se o arquivo foi enviado ao Git

## Etapas de depuração

<Steps>
  <Step title="Leia o erro">
    O log informa exatamente o que falhou e onde.
  </Step>
  <Step title="Teste localmente">
    Execute `jamdesk dev` para reproduzir o erro.
  </Step>
  <Step title="Valide a configuração">
    Execute `jamdesk validate` para verificar sua configuração.
  </Step>
  <Step title="Verifique as alterações recentes">
    Revise seu último commit para identificar o problema.
  </Step>
</Steps>

## Ainda precisa de ajuda?

Se não conseguir resolver o problema:

1. Copie o log completo do build
2. Anote o ID do projeto
3. [Entre em contato com o suporte](/pt/help/support/contact)

## Artigos relacionados

<Columns cols={2}>
  <Card title="Referência de erros" icon="book" href="/pt/help/troubleshooting/error-reference">
    Explicação de todos os códigos de erro
  </Card>
  <Card title="Visão geral da CLI" icon="terminal" href="/pt/cli/overview">
    Teste builds localmente
  </Card>
</Columns>