Le venti diagnosi
Sintomo, causa, soluzione: i venti guasti che questo percorso fa incontrare davvero, aggiornati quando i servizi cambiano.
Questo capitolo si consulta, non si studia. Ed è il capitolo che vale di più, perché ogni scheda che segue è un guasto vero: sono gli intoppi incontrati costruendo PrenotaFacile, con la soluzione che ha funzionato.
Il metodo, prima dell'elenco
Quattro mosse, in quest'ordine.
- Leggi l'errore per intero. Non l'ultima riga: tutte. Il nome del file, il numero di riga e spesso la causa stanno nel mezzo, nella parte che sembra rumore.
- Trova l'anello. Pagina, costruzione, funzione sul server, database, API dell'assistente: ognuno ha una domanda che lo assolve o lo accusa.
- Riproduci. Un guasto che non sai far succedere non lo sai nemmeno riparare: sapresti solo che è sparito.
- Poi chiedi a Claude Code, incollando il testo esatto. Mai «non funziona»: quella non è una descrizione, è un umore.
L'officina
① claude: comando non trovato, subito dopo l'installazione. Il terminale era già aperto quando hai installato, e non vede il percorso nuovo. → Chiudi e riapri il terminale. Se insiste, claude doctor fa la diagnosi dell'installazione. (1.2, 1.3)
② Un comando fallisce con un percorso tagliato a metà nel messaggio. Nel percorso della cartella c'è una &, che il terminale di Windows usa per separare due comandi: tutto quello che viene dopo sparisce. L'errore vero, incontrato costruendo: Cannot find module 'C:\…\Claude Code Projects\next\dist\bin\next', con il percorso troncato esattamente dove cominciava una cartella con la & nel nome. → Sposta il cantiere in una cartella senza &, |, <, >, %. Gli spazi vanno bene, quei caratteri no. (1.2, 1.4)
③ cd risponde che il percorso non esiste, ma la cartella sulla Scrivania la vedi benissimo. Con il backup di OneDrive attivo la Scrivania non è più dove il comando la cerca. → Il gesto unico del libro: scrivi cd con lo spazio finale, poi trascina la cartella dentro la finestra del terminale — il percorso completo si scrive da solo, virgolette comprese. Invio, e pwd per conferma. Il percorso non si indovina, si trascina. (1.4)
④ La creazione del progetto fallisce, o il server di sviluppo non parte. Node è troppo vecchio: la versione di Next.js del libro vuole almeno la 20.9. → node --version, e installa la versione LTS. (1.2, 1.3, 2.2)
Le fondamenta
⑤ npm run dev risponde che non c'è niente da avviare, appena creato il progetto. Sei rimasto nella cartella genitore: il progetto è nella sottocartella appena nata. → cd prenotafacile, poi riprova. Vale per tutto il libro, claude compreso: il comando lavora dove sei, non dove credi di essere. (2.2)
⑥ Il primo commit si rifiuta e git chiede di dirgli chi sei. L'identità di git non è mai stata configurata su questo computer. → Prima controlla che git ci sia (git --version), poi imposta le due righe, una volta per tutte:
git config --global user.name "Nome Cognome"
git config --global user.email "tua@email.it"(2.4)
⑦ Il controllo dei tipi fallisce su un progetto appena scaricato, con Cannot find name 'PageProps'. Non è un difetto del codice: quei tipi non li scrive nessuno, li genera la costruzione dentro .next/types/. Finché quella cartella non esiste, il controllo cerca nomi che non ci sono. → Lancia prima npm run build, poi npx tsc --noEmit. È l'ordine, non il codice. (2.2, 3.6)
⑧ Un prezzo si stampa 1200,00 € invece di 1.200,00 €. Non è un errore: in italiano il separatore delle migliaia compare solo da cinque cifre in su, e mille e duecento ne ha quattro. → Chiedi il raggruppamento sempre attivo nella formattazione. Il difetto si vede solo coi dati veri: con tre servizi finti da 100, 200 e 300 € non compare mai. (2.6)
⑨ Hai pubblicato e online non è cambiato niente — oppure la costruzione è verde qui e rossa lì. Due cause. Sei su un ramo: solo main fa produzione, gli altri fanno anteprima. Oppure manca una variabile d'ambiente sul progetto — e le variabili aggiunte dopo una pubblicazione valgono solo per quelle successive. → Collauda sull'anteprima e poi unisci; aggiungi la variabile e ripubblica. (2.4, 2.5)
I dati
⑩ La query non restituisce niente, ma nel pannello i dati ci sono. Oppure l'inserimento del wizard viene respinto. Le regole di riga sono attive e manca la policy giusta: bloccano tutto, ed è il loro lavoro. → Scrivi o correggi la policy. (3.4)
⑪ L'inserimento viene respinto solo quando chiedi indietro l'identificativo della riga appena creata. returning è una lettura, e sulla tabella delle prenotazioni il pubblico non ha nessuna policy di lettura — per scelta, perché aprirne una vorrebbe dire aprire le prenotazioni di tutti. → Non chiedere niente indietro: l'identificativo lo genera il tuo codice, e la pagina di conferma mostra quello che il cliente ha appena scritto. (3.4)
⑫ Una modifica «riesce» ma non cambia niente, e l'app dice «salvato». Sulle scritture le regole di riga non danno errore: danno zero righe toccate. Un aggiornamento o una cancellazione senza policy che li copra riescono, silenziosamente, senza toccare nulla. → Guarda sempre il numero di righe toccate, non solo l'assenza di errore. (3.4, 3.6)
⑬ Il sito è su ma non legge i dati. Sul piano gratuito il progetto database si mette in pausa dopo sette giorni di inattività. → Riattivalo dal pannello («Resume project»): i dati sono lì. La prevenzione è il calendario del 6.2. (6.2)
L'AI dentro
⑭ L'assistente non risponde. Se l'API risponde 401, la chiave è sbagliata o non è caricata: l'SDK la legge dall'ambiente. Se invece il server dà 500 con il corpo vuoto, il client non è nemmeno partito — è il caso di chi ha dimenticato la chiave. → Ricontrolla .env.local e le variabili d'ambiente del progetto online. E crea il client prima di scrivere nel registro: dodici tentativi falliti avevano lasciato dodici conversazioni aperte e zero risposte, un registro che raccontava dodici clienti ignorati mai esistiti. (4.1, 4.2)
⑮ 429 rate_limit_error. Hai superato il limite del tuo livello d'uso. → Rispetta l'intestazione retry-after e riprova con attesa; il livello avanza da solo con lo storico d'uso. Se la risposta non porta retry-after, non è il limite di velocità: è il tetto di spesa mensile. (4.5)
⑯ Hai messo un limite ai caratteri e la spesa sale lo stesso. Il limite guardava solo l'ultimo messaggio. Misurato: due messaggi da 200.000 caratteri in posizione non finale passavano tutti i controlli — quattrocentomila caratteri in una richiesta sola. → Controlla ogni messaggio e la somma, con un tetto suo. (4.5)
⑰ Il limite per indirizzo non scatta mai. L'intestazione che porta l'indirizzo del visitatore è una lista che ogni intermediario allunga in coda: il primo elemento l'ha scritto chi bussa, quindi cambiarlo non costa niente. Misurato: trenta richieste con il primo elemento sempre diverso, zero respinte. → Leggi dalla fine, non dall'inizio. Con la correzione: diciotto respinte su trenta, e zero fra trenta visitatori davvero diversi. (4.5)
Il mestiere
⑱ Il collaudo è tutto verde e non ha controllato niente. Successo due volte costruendo. La lista di controllo mandava alla rotta dell'assistente un messaggio in un formato che la rotta rifiutava subito: rispondeva 400 alla validazione senza mai arrivare al punto da collaudare — una risposta perfettamente corretta a una domanda sbagliata. E i test coprivano le funzioni interne, mai la rotta pubblica: si poteva spegnere del tutto il limite per indirizzo e la suite restava verde. → Prova ogni controllo contro un difetto che sai esserci. Se non lo trova, il difetto è nel controllo. (3.6, 4.5)
⑲ In un cantiere separato il server dice ✓ Ready e subito dopo che non trova Next.js. Il cantiere è una copia pulita: contiene solo ciò che git conosce, quindi niente node_modules e niente .env.local. I test possono anche passare — cercano i pacchetti risalendo le cartelle — ma il compilatore fissa la radice sul cantiere e si rifiuta di guardare sopra. → npm install lì dentro, e rimetti a mano il file dei segreti. (5.1)
⑳ Un pagamento di prova riesce ma la prenotazione resta ferma. Il completamento dell'ordine non lo fa la pagina di ritorno, lo fa il webhook — e in locale gli eventi arrivano solo se il programma che li inoltra sta girando in una finestra dedicata. → Tieni in esecuzione stripe listen --forward-to localhost:3000/api/webhook, usa il codice whsec_… che stampa, e gestisci l'evento in modo che eseguirlo due volte non faccia danni: la consegna può ripetersi e l'ordine non è garantito. (5.2)
Una scheda che non troverai altrove, e che costa un'ora a chi non la conosce: un test può dirti che due testi identici sono diversi. I prezzi formattati contengono uno spazio speciale, che non è quello della barra spaziatrice. Confronta sempre col risultato della funzione che li formatta, mai con una stringa battuta a mano.
Quando non è in elenco
Il ventunesimo guasto è quello che ti capiterà. Il metodo è quello della prima pagina, più una regola che vale come un cerino: se dopo trenta minuti giri in tondo, fermati. Commit dello stato, sessione nuova, problema ridescritto da zero. Un contesto pulito trova in cinque minuti quello che un contesto stanco non vede in un'ora.
In sintesi
- L'errore si legge per intero: il nome del file e la riga stanno quasi sempre nella parte che sembra rumore.
- Si percorre la catena un anello alla volta, e il primo che risponde male è quasi sempre la causa, non la conseguenza.
- Un guasto si riproduce prima di ripararlo: altrimenti non sai perché si è rotto, e nemmeno perché ha smesso.
- Un controllo va provato contro un difetto noto — un verde che non ha mai visto un rosso non ha mai dimostrato niente.
- Dopo trenta minuti in tondo, contesto nuovo: costa meno di un'altra ora nello stesso vicolo.
Rompi l'app apposta, in locale: rinomina la variabile d'ambiente della chiave dell'assistente. Poi ripercorri la catena senza guardare che cosa hai toccato, finché la diagnosi non ti porta esattamente lì.
Sai costruire, mantenere e riparare. Resta una cosa sola: rifarlo per qualcun altro.