Riferimento errori di build

Trova il tuo codice di errore con Ctrl/Cmd+F oppure sfoglia per categoria: configurazione, MDX, OpenAPI, timeout e asset.

Errori di configurazione

INVALID_DOCS_JSON

Messaggio: "Configurazione docs.json non valida"

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

Soluzione:

1. Esegui jamdesk validate in locale per vedere gli errori dettagliati
2. Verifica la presenza di virgole, parentesi o virgolette mancanti
3. Controlla che tutti i valori corrispondano allo schema previsto

MISSING_PAGE

Messaggio: "Pagina 'path/to/page' referenziata nella navigazione ma file non trovato"

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

Soluzione:

1. Verifica che il file esista nel percorso indicato
2. Controlla che il percorso in docs.json corrisponda al nome effettivo del file (senza .mdx)
3. Verifica le maiuscole e minuscole. I percorsi distinguono tra maiuscole e minuscole

INVALID_FRONTMATTER

Messaggio: "Frontmatter non valido in 'path/to/page'"

Causa: Il frontmatter YAML all'inizio di un file MDX è malformato.

Soluzione:

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

Errori MDX

MDX_SYNTAX_ERROR

Messaggio: "Compilazione MDX non riuscita"

Causa: Sintassi MDX o JSX non valida nei contenuti.

Soluzione:

1. Assicurati che tutti i tag JSX siano chiusi correttamente (<Card>...</Card>)
2. Verifica che le prop usino la sintassi corretta (title="valore" e non title=valore)
3. Escapa le parentesi graffe nel testo normale: \{ invece di {

COMPONENT_NOT_FOUND

Messaggio: "Componente sconosciuto 'ComponentName'"

Causa: Stai usando un componente che non esiste in Jamdesk.

Soluzione:

1. Controlla 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: "Prop non valide per il componente 'ComponentName'"

Causa: Un componente ha ricevuto prop che non accetta.

Soluzione:

1. Consulta la documentazione del componente per le prop valide
2. Rimuovi le prop non supportate
3. Verifica il tipo previsto della prop nella documentazione del componente (ad esempio, cols si aspetta un numero, non una stringa)

Errori OpenAPI

OPENAPI_PARSE_ERROR

Messaggio: "Impossibile analizzare la specifica OpenAPI"

Causa: Il file della specifica OpenAPI ha una sintassi o una struttura non valida.

Soluzione:

1. Esegui jamdesk openapi-check per validare in locale
2. Usa un validatore OpenAPI come Swagger Editor
3. Verifica la sintassi JSON o YAML

OPENAPI_REFERENCE_ERROR

Messaggio: "Riferimento non risolto nella specifica OpenAPI"

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 esterno o a un URL, conferma che il file sia incluso nel progetto e che l'URL sia raggiungibile

Timeout della build

BUILD_TIMEOUT

Messaggio: "La build ha superato il tempo massimo consentito"

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

Soluzione:

1. Ottimizza le immagini grandi (comprimile o ridimensionale)
2. Dividi le pagine molto grandi in pagine più piccole
3. Riduci il numero di pagine se è estremamente elevato
4. Contatta il supporto se il problema persiste

Errori degli asset

ASSET_NOT_FOUND

Messaggio: "Asset 'path/to/asset' non trovato"

Causa: Un'immagine o un file referenziato nella documentazione non esiste.

Soluzione:

1. Verifica che il file esista nel percorso indicato
2. Controlla che il percorso sia relativo alla directory della documentazione
3. Rispetta esattamente maiuscole e minuscole nel nome del file. I percorsi distinguono tra maiuscole e minuscole

ASSET_TOO_LARGE

Messaggio: "L'asset supera la dimensione massima del file"

Causa: Un'immagine o un file è più grande del limite di 10 MB.

Soluzione:

1. Comprimi le immagini con strumenti come TinyPNG o ImageOptim
2. Usa i formati appropriati (WebP per le foto, SVG per le icone)
3. Ospita all'esterno i file molto grandi

Come ottenere assistenza

Se non riesci a risolvere un errore:

1. Controlla il log di build completo nella tua dashboard per maggiore contesto
2. Cerca nelle domande frequenti i problemi più comuni
3. Contatta il supporto indicando l'ID del progetto e i dettagli dell'errore

Articoli correlati