---
title: Riferimento errori di build
description: "Codici di errore di build, cause e soluzioni: configurazione, sintassi MDX, OpenAPI, timeout e asset."
---

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

Trova il codice dell'errore con Ctrl/Cmd+F oppure consulta le categorie: configurazione, MDX, OpenAPI, timeout e asset.

## Errori di configurazione

### INVALID_DOCS_JSON

**Messaggio:** "Invalid docs.json configuration"

**Causa:** Il file `docs.json` contiene errori di sintassi o valori non validi.

**Soluzione:**
1. Esegui `jamdesk validate` localmente per visualizzare gli errori dettagliati
2. Controlla la presenza di virgole, parentesi o virgolette mancanti
3. Verifica che tutti i valori corrispondano allo schema previsto

### MISSING_PAGE

**Messaggio:** "Page 'path/to/page' referenced in navigation but file not found"

**Causa:** Una pagina elencata nella navigazione di `docs.json` non esiste.

**Soluzione:**
1. Controlla che il file esista nel percorso specificato
2. Verifica che il percorso in `docs.json` corrisponda al nome file effettivo (senza `.mdx`)
3. I percorsi distinguono tra maiuscole e minuscole, quindi controlla le maiuscole

### INVALID_FRONTMATTER

**Messaggio:** "Invalid frontmatter in 'path/to/page'"

**Causa:** Il frontmatter YAML all'inizio di un file MDX non è valido.

**Soluzione:**
1. Assicurati che il frontmatter inizi e termini con `---`
2. Controlla la sintassi YAML non valida (due punti mancanti, indentazione errata)
3. Racchiudi tra virgolette le stringhe che contengono caratteri speciali

## Errori MDX

### MDX_SYNTAX_ERROR

**Messaggio:** "MDX compilation failed"

**Causa:** Sintassi MDX o JSX non valida nel contenuto.

**Soluzione:**
1. Assicurati che tutti i tag JSX siano chiusi correttamente (`<Card>...</Card>`)
2. Controlla che le proprietà usino la sintassi corretta (`title="value"` e non `title=value`)
3. Esegui l'escape delle parentesi graffe nel testo normale: `\{` invece di `{`

### COMPONENT_NOT_FOUND

**Messaggio:** "Unknown component 'ComponentName'"

**Causa:** Stai utilizzando un componente che non esiste in Jamdesk.

**Soluzione:**
1. Consulta il [riferimento dei componenti](/it/components/overview) per i nomi corretti
2. I componenti distinguono tra maiuscole e minuscole: usa `<Card>` e non `<card>`
3. Verifica di non importare componenti personalizzati (non supportati)

### INVALID_PROPS

**Messaggio:** "Invalid props for component 'ComponentName'"

**Causa:** Un componente ha ricevuto proprietà che non accetta.

**Soluzione:**
1. Consulta la documentazione del componente per conoscere le proprietà valide
2. Rimuovi le proprietà non supportate
3. Controlla il tipo previsto per la proprietà nella documentazione del componente (ad esempio, `cols` richiede un numero, non una stringa)

## Errori OpenAPI

### OPENAPI_PARSE_ERROR

**Messaggio:** "Failed to parse OpenAPI specification"

**Causa:** Il file della specifica OpenAPI contiene sintassi o struttura non valide.

**Soluzione:**
1. Esegui `jamdesk openapi-check` localmente per convalidare il file
2. Usa un validatore OpenAPI come Swagger Editor
3. Controlla che la sintassi JSON o YAML sia valida

### OPENAPI_REFERENCE_ERROR

**Messaggio:** "Unresolved reference in OpenAPI spec"

**Causa:** Un `$ref` nella specifica OpenAPI punta a una definizione inesistente.

**Soluzione:**
1. Verifica che tutti i percorsi `$ref` siano corretti
2. Controlla che gli schemi referenziati esistano in `components/schemas`
3. Se un `$ref` punta a un file o URL esterno, verifica che il file sia incluso nel progetto e che l'URL sia raggiungibile

## Timeout della build

### BUILD_TIMEOUT

**Messaggio:** "Build exceeded maximum time limit"

**Causa:** La build ha richiesto più tempo del limite consentito (di solito 5 minuti).

**Soluzione:**
1. Ottimizza le immagini di grandi dimensioni (comprimile o ridimensionalle)
2. Dividi le pagine molto grandi in pagine più piccole
3. Riduci il numero di pagine se il progetto è estremamente grande
4. Contatta il supporto se il problema persiste

## Errori degli asset

### ASSET_NOT_FOUND

**Messaggio:** "Asset 'path/to/asset' not found"

**Causa:** Un'immagine o un file a cui fanno riferimento i tuoi documenti non esiste.

**Soluzione:**
1. Verifica che il file esista nel percorso specificato
2. Controlla che il percorso sia relativo alla directory dei documenti
3. I percorsi distinguono tra maiuscole e minuscole, quindi controlla esattamente il nome del file

### ASSET_TOO_LARGE

**Messaggio:** "Asset exceeds maximum file size"

**Causa:** Un'immagine o un file supera il limite di 10 MB.

**Soluzione:**
1. Comprimi le immagini usando strumenti come TinyPNG o ImageOptim
2. Usa formati appropriati (WebP per le foto, SVG per le icone)
3. Valuta la possibilità di ospitare esternamente i file molto grandi

## Come ottenere assistenza

Se non riesci a risolvere un errore:

1. Controlla il log completo della build nella dashboard per ulteriori dettagli
2. Cerca nella [FAQ](/it/help/faq) i problemi più comuni
3. [Contatta il supporto](/it/help/support/contact) fornendo l'ID del progetto e i dettagli dell'errore

## Articoli correlati

<Columns cols={2}>
  <Card title="Errori di build" icon="triangle-exclamation" href="/it/help/troubleshooting/build-failures">
    Errori di build comuni e relative soluzioni
  </Card>
  <Card title="Contatta il supporto" icon="headset" href="/it/help/support/contact">
    Ricevi assistenza dal nostro team
  </Card>
</Columns>