Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Errori e debugger1. Leggere un tracebackp. 1

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.

Python
ritardi = {"M12": 2, "M14": 0, "M16": 5}

print("Ritardo di M14:", ritardi["M14"])
print("Ritardo di M18:", ritardi["M18"])
Terminale
python ritardi.py
Ritardo 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:

ritardi = {"M12": 2, "M14": 0, "M16": 5}ritardidict"M12"2"M14"0"M16"5
Il dizionario dei ritardi, senza M18

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)
MossaDove guardiCosa ti dice
1. CosaL'ultima rigaIl nome dell'errore (KeyError) e un messaggio: qui 'M18', la chiave che non c'è
2. Quale pezzoLa riga di codice sopra, e i segni sottoLa riga che si è rotta, e il pezzo preciso: ["M18"]
3. DoveLa riga che comincia con FileIl 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:

Python
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 str

Una 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.

Python
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 è rotto

in <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.

Python
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 percorsoDi 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 similiPezzi 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.

Python
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:

  1. Niente Traceback (most recent call last): non c'è nessuna strada di chiamate, il programma non è mai partito.
  2. Nemmeno la prima riga è girata: Controllo del tornello non compare. Python legge tutto il file prima di cominciare, e se non lo capisce non esegue niente.
  3. La ^ sta dove Python si è perso, che spesso è un attimo dopo l'errore vero. Qui è subito dopo il 5, 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.

Python
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:

Terminale
curl -i http://127.0.0.1:8000/treni/M99/ritardo
HTTP/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 Error

500 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:

  1. Vai all'ultima riga. Quel nome di errore è quello che conta.
  2. Risali finché trovi il primo percorso che è il tuo (la cartella del progetto, non site-packages).
  3. 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 File dice 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.12 e di site-packages non sono tuoi.
  • Il SyntaxError non ha il Traceback: 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.