Leggere un traceback
Dal basso, una riga alla volta
- 10 minuti di lettura
Quando un programma si pianta, Python non ti lascia con le mani vuote: ti scrive una lettera. Quella lettera si chiama traceback, ed è la cosa più utile che il computer ti dia in tutto il corso.
Il problema è che sembra un muro. Righe lunghe, percorsi, segni strani. La buona notizia: si legge sempre nello stesso modo, e si comincia dal fondo.
Prendiamo un programma di quattro righe. Il tabellone di Piazza Query ha un dizionario con i ritardi dei treni, e il programma ne stampa due.
ritardi = {"M12": 2, "M14": 0, "M16": 5}
print("Ritardo di M14:", ritardi["M14"])
print("Ritardo di M18:", ritardi["M18"])python ritardi.pyRitardo di M14: 0
Traceback (most recent call last):
File "/home/lucia/linea-menta/ritardi.py", line 4, in <module>
print("Ritardo di M18:", ritardi["M18"])
~~~~~~~^^^^^^^
KeyError: 'M18'La prima riga ha funzionato (Ritardo di M14: 0) e Python è andato avanti finché non ha potuto più. Poi si è fermato e ha scritto il resto.
Il disegno. Il dizionario nel momento dell'errore:
Il disegno
Ogni traceback ha tre pezzi che ti servono, e vanno letti in quest'ordine: dal basso verso l'alto.
Traceback (most recent call last):
File "/home/lucia/linea-menta/ritardi.py", line 4, in <module> ← 3. DOVE: il file, la riga, la funzione
print("Ritardo di M18:", ritardi["M18"]) ← 2. QUALE RIGA DI CODICE
~~~~~~~^^^^^^^ ← e quale pezzo: i segni
KeyError: 'M18' ← 1. COSA: il nome dell'errore e il messaggio
(si comincia da qui)| Mossa | Dove guardi | Cosa ti dice |
|---|---|---|
| 1. Cosa | L'ultima riga | Il nome dell'errore (KeyError) e un messaggio: qui 'M18', la chiave che non c'è |
| 2. Quale pezzo | La riga di codice sopra, e i segni sotto | La riga che si è rotta, e il pezzo preciso: ["M18"] |
| 3. Dove | La riga che comincia con File | Il file, il numero di riga, il nome della funzione |
Il nome dell'errore ha un capitolo tutto suo: Gli errori per nome. Qui basta saperlo trovare.
I segni: ~ e ^
Sotto la riga di codice Python disegna una striscia. Serve a dirti quale pezzo della riga si è rotto, perché in una riga lunga ce ne sono tanti.
^sta sotto il pezzo che ha fatto scattare l'errore;~sta sotto il resto dell'espressione, quello che gli stava intorno.
Nell'esempio di prima la ~ copre ritardi e la ^ copre ["M18"]: l'errore è nelle parentesi quadre, non nel print. Con un'operazione la ^ va proprio sotto il simbolo:
corse = 12
print("Corse di oggi: " + corse)Traceback (most recent call last):
File "/home/lucia/linea-menta/tabellino.py", line 2, in <module>
print("Corse di oggi: " + corse)
~~~~~~~~~~~~~~~~~~^~~~~~~
TypeError: can only concatenate str (not "int") to strUna sola ^, sotto il +. Python ti dice: il guaio è in quella somma, tra un testo e un numero.
Più blocchi: la strada delle chiamate
Finora c'era un blocco solo (File … più la riga di codice). Quando una funzione ne chiama un'altra, i blocchi sono più di uno. Sono in ordine di chiamata: il primo è da dove è partito tutto, l'ultimo è dove si è rotto.
def minuti_di_guida(inizio, fine):
return fine - inizio
def ore_di_guida(inizio, fine):
return minuti_di_guida(inizio, fine) / 60
print(ore_di_guida(480, 600))
print(ore_di_guida(480, "12:05"))2.0
Traceback (most recent call last):
File "/home/lucia/linea-menta/turno.py", line 10, in <module>
print(ore_di_guida(480, "12:05"))
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/lucia/linea-menta/turno.py", line 6, in ore_di_guida
return minuti_di_guida(inizio, fine) / 60
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/lucia/linea-menta/turno.py", line 2, in minuti_di_guida
return fine - inizio
~~~~~^~~~~~~~
TypeError: unsupported operand type(s) for -: 'str' and 'int'Tre blocchi. Letti dall'alto sono una staffetta:
riga 10, in <module> ore_di_guida(480, "12:05") ── chiama ──▶
riga 6, in ore_di_guida minuti_di_guida(inizio, fine) / 60 ── chiama ──▶
riga 2, in minuti_di_guida fine - inizio ■ qui si è rottoin <module> vuol dire «nel file stesso, fuori da ogni funzione». Si legge <module> e si pensa: il programma principale.
Dal basso, la lettura è questa. Ultima riga: un TypeError, hai sottratto un numero a un testo. Il blocco più in basso: è successo alla riga 2, in minuti_di_guida. Ma perché fine era un testo? Non lo scopri lì: lo scopri nel blocco sopra, dove la funzione è stata chiamata, e più su ancora, alla riga 10, dove qualcuno ha scritto "12:05" tra virgolette.
Il tuo file e quelli degli altri
Un traceback non parla solo del tuo codice. Se chiami una funzione di Python o di una libreria, e lei si rompe, nel traceback compaiono anche i suoi file.
from datetime import datetime
ora = datetime.strptime("25:70", "%H:%M")
print(ora)Traceback (most recent call last):
File "/home/lucia/linea-menta/orario.py", line 3, in <module>
ora = datetime.strptime("25:70", "%H:%M")
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/_strptime.py", line 653, in _strptime_datetime
tt, fraction, gmtoff_fraction = _strptime(data_string, format)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/_strptime.py", line 432, in _strptime
raise ValueError("time data %r does not match format %r" %
ValueError: time data '25:70' does not match format '%H:%M'Il blocco più in basso è dentro _strptime.py, che non hai scritto tu. Non andare a ritoccarlo: Python e le librerie sono scritte da gente brava e provate da milioni di persone. L'ora 25:70 non esiste, ed è giusto che si arrabbi.
Come si capisce di chi è un file: dal percorso.
| Il percorso | Di chi è |
|---|---|
/home/lucia/linea-menta/orario.py (la tua cartella) | Tuo |
…/.venv/lib/python3.12/site-packages/… | Una libreria installata con pip (fastapi, pytest, …) |
/usr/lib/python3.12/… | La libreria standard di Python (json, datetime, …) |
<frozen runpy> e simili | Pezzi interni di Python |
La regola: cerca il blocco più in basso che è tuo. Lì guardi la riga, e ti chiedi: cosa ho passato a questa funzione? Qui ho passato "25:70": ecco il colpevole.
Quando non c'è il traceback: il SyntaxError
C'è un errore che non somiglia agli altri. Succede quando la frase che hai scritto non è Python valido: manca un :, una parentesi, una virgoletta.
print("Controllo del tornello")
ritardo = 7
if ritardo > 5
print("Avvisa la centrale") File "/home/lucia/linea-menta/controllo.py", line 3
if ritardo > 5
^
SyntaxError: expected ':'Tre differenze:
- Niente
Traceback (most recent call last): non c'è nessuna strada di chiamate, il programma non è mai partito. - Nemmeno la prima riga è girata:
Controllo del tornellonon compare. Python legge tutto il file prima di cominciare, e se non lo capisce non esegue niente. - La
^sta dove Python si è perso, che spesso è un attimo dopo l'errore vero. Qui è subito dopo il5, e infatti manca proprio un:lì. Se non lo trovi, guarda anche la riga prima.
Due traceback in fila
A volte ne trovi due, uno sopra l'altro, con una frase in mezzo.
ritardi = {"M12": 2}
try:
print(ritardi["M99"])
except KeyError:
print(int("tre"))Traceback (most recent call last):
File "/home/lucia/linea-menta/fallback.py", line 4, in <module>
print(ritardi["M99"])
~~~~~~~^^^^^^^
KeyError: 'M99'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/home/lucia/linea-menta/fallback.py", line 6, in <module>
print(int("tre"))
^^^^^^^^^^
ValueError: invalid literal for int() with base 10: 'tre'Leggi l'ultimo: è quello che ha fermato il programma. Il primo è la storia di come ci si è arrivati: mentre Python gestiva un errore (KeyError), ne è successo un secondo (ValueError). Il try e l'except te li insegna il capitolo dopo: per ora ti basta sapere che la frase During handling… vuol dire «sotto c'è l'ultimo, sopra la causa».
I traceback lunghi di FastAPI
Quando avrai un server FastAPI (lo costruisci in Il primo server), vedrai i traceback più lunghi di tutti.
Prima cosa: il browser, o /docs, o curl, non ti dicono niente di utile. Dicono soltanto che qualcosa è andato storto:
curl -i http://127.0.0.1:8000/treni/M99/ritardoHTTP/1.1 500 Internal Server Error
date: Thu, 19 Nov 2026 17:33:19 GMT
server: uvicorn
content-length: 21
content-type: text/plain; charset=utf-8
Internal Server Error500 Internal Server Error vuol dire «il server ha avuto un problema». Il traceback non è lì: è nel terminale dove hai acceso il server. Torna a guardare quella finestra, e scorri in fondo.
Troverai decine di blocchi, quasi tutti con site-packages nel percorso (uvicorn, fastapi, starlette, anyio): sono le librerie che portano la richiesta fino alla tua funzione. Non sono mai loro il problema. Il tuo codice è in fondo, uno o due blocchi in mezzo a tutto quel rumore.
Il metodo è lo stesso di sempre, solo con più pazienza:
- Vai all'ultima riga. Quel nome di errore è quello che conta.
- Risali finché trovi il primo percorso che è il tuo (la cartella del progetto, non
site-packages). - Quello è il tuo blocco. Se ce n'è uno solo, hai finito. Se ce ne sono due, il più in basso è dove si è rotto, quello sopra è chi lo ha chiamato.
Un traceback vero di un server lo leggi passo per passo nella pagina degli esercizi spiegati, qui accanto.
Ricorda
- Un traceback si legge dal basso.
- L'ultima riga dice cosa (il nome dell'errore e il messaggio). La riga di codice sopra dice quale riga; i segni, quale pezzo; la riga
Filedice dove. - Più blocchi sono la strada delle chiamate: il primo è l'inizio, l'ultimo è dove si è rotto, e chi ha passato il dato storto sta un blocco più su.
- Cerca il blocco più in basso che è tuo: i file di
lib/python3.12e disite-packagesnon sono tuoi. - Il
SyntaxErrornon ha ilTraceback: il programma non parte, e la^è dove Python si è perso. - Con FastAPI il browser dice solo
500: il traceback è nel terminale del server, in fondo.