Build failed nel deploy: cos'è e come leggere il log

Hai premuto «Pubblica» e invece dell'app online ti ritrovi un messaggio come «Build failed» o «Deploy failed»? Vuol dire che la piattaforma non è riuscita a preparare la versione pubblica della tua app, e quindi non l'ha messa online. Succede spesso con le app create con l'AI su Bolt, Lovable, Vercel o Netlify, e la causa è quasi sempre scritta nero su bianco nel log della build. In questa guida ti spieghiamo cos'è la build, come leggere il log senza farti spaventare e quali sono gli errori di deploy più comuni.

Cos'è la build, in parole semplici

Il codice che l'AI scrive per te non è pronto per essere spedito così com'è al browser. Prima va trasformato: i file vengono controllati, uniti, compressi e convertiti in un formato che qualsiasi browser capisce. Questo processo si chiama build. Il deploy è il passo successivo: prendere il risultato della build e metterlo online.

Immagina una tipografia che deve stampare un libro. Se una pagina rimanda a un capitolo che non esiste, o manca un'immagine, la stampa si ferma: meglio non stampare nulla che stampare un libro sbagliato. La build fa lo stesso. Quando si blocca, il deploy non parte, e il messaggio che vedi è «Build failed».

Una buona notizia: su servizi come Vercel e Netlify, se una build fallisce, la versione precedente resta online. I tuoi utenti continuano a vedere l'ultima versione funzionante mentre tu sistemi il problema.

Perché in anteprima funziona e la build no

È la domanda che si fanno tutti. Le ragioni principali sono quattro.

• L'anteprima è più tollerante. Durante lo sviluppo molti controlli vengono saltati per andare più veloci. La build invece verifica tutto, compresi i controlli di TypeScript, un linguaggio che aggiunge a JavaScript regole sui tipi di dati («questo campo è un numero», «questo è un testo»).
• Maiuscole e minuscole contano. I server che fanno la build usano quasi sempre Linux, dove Header.tsx e header.tsx sono due file diversi. Su Mac e Windows, di solito, sono lo stesso file.
• Versioni diverse. Il server può usare una versione diversa di Node.js (il programma che esegue la build) o delle librerie su cui si appoggia l'app.
• Mancano impostazioni. Alcune variabili d'ambiente servono già durante la build, non solo quando l'app è online. Se nel pannello dell'hosting non ci sono, la build si blocca oppure produce un'app che non funziona. Ne parliamo nella guida sulle variabili d'ambiente.

Come leggere il log della build

Il log è il registro di tutto quello che la piattaforma ha fatto durante la build, riga per riga. Su Vercel e Netlify lo trovi aprendo il deploy fallito; sulle piattaforme AI l'errore compare di solito nella finestra di pubblicazione o in chat. Sembra un muro di testo, ma per orientarti bastano tre regole.

1. L'ultima riga non è la causa. Le righe finali dicono solo che qualcosa è andato storto. Su Vercel, per esempio:

Error: Command "npm run build" exited with 1

Su Netlify, invece:

Build script returned non-zero exit code: 2

Tradotto: «il comando di build si è fermato con un errore». Il perché è più in alto.

2. Cerca il primo errore. Scorri verso l'alto, oppure usa la ricerca del browser (Ctrl+F, o Cmd+F su Mac) con la parola error. Il primo messaggio di errore è quello che conta: gli altri spesso sono conseguenze.

3. Annota file e riga. Spesso l'errore indica dove si trova il problema, con una riga come questa:

src/pages/Dashboard.tsx(42,18): error TS2339: Property 'nome' does not exist on type 'Utente'.

Qui la build dice: nel file Dashboard.tsx, alla riga 42, il codice usa un campo nome che secondo le regole di TypeScript non esiste. Con questa informazione l'AI, o uno sviluppatore, sa esattamente dove guardare.

Gli errori di build più comuni

Il file package-lock.json (o pnpm-lock.yaml, a seconda dello strumento usato) fissa la versione esatta di ogni libreria. Se l'AI aggiunge una libreria ma questo file non viene aggiornato, il server si rifiuta di procedere. È una protezione, non un capriccio: evita che online finisca una combinazione di librerie diversa da quella che hai provato.

Cosa puoi fare tu, passo per passo

1. Apri il log completo del deploy fallito, non solo il riepilogo.
2. Trova il primo errore e copialo parola per parola, insieme al nome del file e al numero di riga.
3. Chiediti cosa è cambiato. Se la build funzionava ieri, il problema è quasi sempre nelle ultime modifiche. Se il codice è su GitHub, la cronologia dei commit ti mostra cosa è stato toccato; se non ce l'hai ancora, ecco come esportare il progetto su GitHub.
4. Chiedi all'AI una correzione mirata. Incolla l'errore esatto e scrivi qualcosa come: «La build online fallisce con questo errore. Spiegami la causa e correggi solo questo, senza modificare altro».
5. Una correzione alla volta. Dopo ogni modifica ripubblica e rileggi il log: a volte, sistemato un errore, ne compare un altro che prima era nascosto. È normale.
6. Non forzare le installazioni. Se il problema sono le versioni delle librerie, aggirare l'errore con opzioni che «forzano» l'installazione sposta il problema più avanti. Meglio allineare le versioni o tornare all'ultima combinazione che funzionava.

Un'avvertenza sul punto 4. Se l'AI risponde a un singolo errore modificando dieci file diversi, fermati. È il segnale che sta tirando a indovinare, e da lì al circolo vizioso degli errori il passo è breve: lo spieghiamo nell'articolo su quando l'AI continua a rompere il codice.

Se invece la build va a buon fine ma online vedi solo una pagina bianca, il problema è un altro e si cerca altrove: trovi la guida dedicata nell'articolo sulla pagina bianca dopo il deploy.

Quando conviene farti aiutare

Se l'errore nel log non ti dice nulla, se le correzioni dell'AI generano nuovi errori a catena, o se la build fallisce per problemi di versioni e di memoria, è il momento di farsi affiancare. Sono problemi che di solito si risolvono in fretta quando si sa dove guardare, e molto lentamente quando si procede a tentativi.

Durante una call gratuita di 20 minuti possiamo guardare insieme il log: ti diciamo qual è la causa e cosa serve per sbloccare la pubblicazione.