Riferimento errori di build

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 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 i problemi più comuni
3. Contatta il supporto fornendo l'ID del progetto e i dettagli dell'errore

Articoli correlati