La sessione, se qualcosa va storto
Gli errori della sessione, uno per uno
Gli errori che vedrai di più in questo capitolo. Per ognuno: cosa leggi, cosa vuol dire, cosa fai. Il capitolo è uno dei più difficili del libro: è normale sbagliare, e quasi tutti gli errori hanno un nome che dice già dove cercare.
Ricorda come si legge un traceback: dal basso. L'ultima riga dice cosa, la riga con File … line … dice dove. Tutto il resto è nel capitolo Leggere un traceback.
Il 500 e dove guardare
Quando una rotta si rompe, il client non vede niente di utile:
$ curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "km": 0, "in_servizio": false}'
HTTP/1.1 500 Internal Server Error
date: Thu, 19 Nov 2026 18:10:17 GMT
server: uvicorn
content-length: 21
content-type: text/plain; charset=utf-8
Internal Server ErrorIl 500 è solo il segnale: l'errore vero è nel terminale del server, in fondo al traceback. In questo caso:
File "~/corso/db-sessione/palestra/rotta_guasta.py", line 45, in nuovo_treno
db.refresh(treno)
File "~/corso/db-sessione/.venv/lib/python3.12/site-packages/sqlalchemy/orm/session.py", line 3364, in refresh
self._expire_state(state, attribute_names)
File "~/corso/db-sessione/.venv/lib/python3.12/site-packages/sqlalchemy/orm/session.py", line 3490, in _expire_state
self._validate_persistent(state)
File "~/corso/db-sessione/.venv/lib/python3.12/site-packages/sqlalchemy/orm/session.py", line 4410, in _validate_persistent
raise sa_exc.InvalidRequestError(
sqlalchemy.exc.InvalidRequestError: Instance '<TrenoDB at 0x10efe6780>' is not persistent within this SessionLe ultime righe dicono tutto: la riga della tua rotta (line 45, in nuovo_treno, la riga con db.refresh(treno)) e il nome dell'errore. Qui manca il commit. Con pytest invece non c'è nessun 500: TestClient ti fa vedere direttamente l'eccezione, e il test è rosso con lo stesso messaggio. Come si ispeziona una rotta con il debugger: Il debugger con FastAPI e i test.
Gli errori con un nome
| Leggi | Vuol dire | Cosa fai |
|---|---|---|
FastAPIError: Invalid args for response field! Hint: check that <class 'sqlalchemy.orm.session.Session'> is a valid Pydantic field type | Il parametro db non ha Depends: FastAPI crede che sia un dato che arriva dal client, e non sa che tipo di dato sia Session. Succede appena accendi il server, non alla richiesta | db: Session = Depends(get_db), completo |
FastAPIError: Invalid args for response field! Hint: check that <class 'modelli.TrenoDB'> is a valid Pydantic field type | Nel def hai scritto -> TrenoDB: la classe-tabella al posto dello stampo | Dopo la freccia va lo stampo: -> Treno, oppure -> list[Treno] |
TypeError: <generator object get_db at 0x…> is not a callable object | Hai scritto Depends(get_db()): la funzione l'hai chiamata tu | Depends(get_db), senza parentesi |
AttributeError: 'NoneType' object has no attribute 'codice' | db.get o db.scalar hanno risposto None (la riga non c'è) e sei andato avanti | Subito dopo: if treno is None: e raise HTTPException(status_code=404, …) |
ResponseValidationError … Input should be a valid dictionary or object to extract fields from, con 'input': None | La rotta ha restituito None: manca l'if … is None | L'if con il 404, prima del return |
ResponseValidationError … Field required, con 'input': (<modelli.StazioneDB object at 0x…>,) | Hai usato db.execute(…).all(): arrivano righe, ognuna con un oggetto dentro, non gli oggetti | db.scalars(…).all() |
ArgumentError: Column expression, FROM clause, or other columns clause element expected, got <class '…Treno'>. | In select(…) hai messo lo stampo (Treno) | select(TrenoDB): dentro va la classe-tabella |
NoInspectionAvailable: No inspection system is available for object of type <class 'pydantic._internal._model_construction.ModelMetaclass'> | Hai passato lo stampo a db.get | db.get(TrenoDB, treno_id) |
UnmappedInstanceError: Class '__main__.Treno' is not mapped (o un nome di modulo al posto di __main__) | A db.add hai dato un oggetto Pydantic, non una classe-tabella | db.add(TrenoDB(…)): crea un TrenoDB dai dati dello stampo |
UnmappedInstanceError: Class 'builtins.NoneType' is not mapped | A db.delete (o db.add) hai passato None: la riga non c'era | if … is None con il 404, prima di db.delete |
DataError: (psycopg.errors.InvalidTextRepresentation) invalid input syntax for type integer: "B-07" | db.get vuole l'id, un numero, e tu gli hai dato un badge (o un fascicolo): un testo | db.scalar(select(…).where(Classe.colonna == valore)) |
TypeError: 'carrozze' is an invalid keyword argument for TrenoDB | Una colonna che non esiste nella classe-tabella | Guarda modelli.py: i nomi sono quelli |
InvalidRequestError: Instance '<TrenoDB at 0x…>' is not persistent within this Session | Hai fatto db.refresh su un oggetto che non è stato salvato: manca il db.commit() (o il db.add) | add, commit, e solo dopo refresh |
IntegrityError: (psycopg.errors.UniqueViolation) duplicate key value violates unique constraint "personale_badge_key" | Hai scritto un valore che deve essere unico, e c'è già: il database ha detto no | Controlla prima, con db.scalar, e rispondi 409 |
IntegrityError: (psycopg.errors.ForeignKeyViolation) … Key (stazione_id)=(42) is not present in table "stazioni" | Il valore punta a una riga che non esiste | Controlla prima con db.get e rispondi 404 |
PendingRollbackError: This Session's transaction has been rolled back due to a previous exception during flush | La sessione ha avuto un errore (di solito un IntegrityError preso con except) e non l'hai rimessa a posto | db.rollback() subito dopo l'except |
OperationalError: (psycopg.OperationalError) connection failed: … FATAL: database "db_sessione_manca" does not exist | Il database con quel nome non c'è | createdb db_sessione, poi psql -d db_sessione -f linea_menta.sql |
ProgrammingError: (psycopg.errors.UndefinedTable) relation "treni" does not exist | Il database c'è, ma è vuoto | psql -d db_sessione -f linea_menta.sql |
assert 501 == 200 | C'è ancora la riga del «da fare» | Al suo posto, il tuo codice |
Gli errori che non danno errori
I più difficili sono quelli senza traceback: la rotta risponde, la risposta sembra giusta, ma il database non è come dovrebbe. In questo capitolo sono quasi sempre uno di questi.
Il commit dimenticato (in una modifica o in una cancellazione). La rotta risponde 200 o 204, e il database non cambia. Se hai fatto add e refresh ti salva un errore (is not persistent); se hai cambiato un attributo o fatto delete, niente: la risposta mostra il treno già cambiato perché l'oggetto in memoria è cambiato. La prova del nove è sempre la stessa: guarda il database con psql -d db_sessione -c "SELECT …". Oppure accendi il server e guarda nel suo terminale: se non vedi la riga COMMIT, non è partita nessuna scrittura.
Il flush al posto del commit. Il database riceve il SQL (la riga INSERT compare nel terminale del server) ma non lo conferma: manca la riga COMMIT. La risposta è un perfetto 201, con l'id giusto, e il dato non c'è.
Il where che manca. Una select senza where non è un errore: torna tutta la tabella. Se una lista è più lunga del previsto, guarda la domanda con print(domanda): il SQL dice cosa chiedi davvero.
db.scalar su un campo che si ripete. Dà la prima riga e le altre le perde, senza dirti niente. Se vuoi tutte le righe, db.scalars(…).all().
L'ordine che non c'è. Senza order_by il database non promette nessun ordine: una volta le righe escono come le hai scritte, un'altra no. Se l'ordine conta, scrivilo.
Due cose che non sono errori, anche se sembrano:
db.scalars(…)senza.all()funziona: FastAPI scorre il risultato da solo. Tieni.all()per avere una lista vera.- Niente
db.refreshdopo ilcommitfunziona: l'oggetto si ricarica da solo quando lo leggi. Tienilo per chiarezza.
Come guardare cosa fa la sessione
Il modo più veloce per capire cosa succede è guardare il SQL. database.py ha echo=True: nel terminale del server, per ogni richiesta, vedi BEGIN, le SELECT, le INSERT o gli UPDATE o i DELETE, e infine COMMIT o ROLLBACK. Leggilo con queste domande:
| Se nel terminale vedi… | Vuol dire |
|---|---|
BEGIN, SELECT …, ROLLBACK | una lettura, o una rotta che si è fermata prima di scrivere (un 404, un 409) |
BEGIN, INSERT … o UPDATE … o DELETE …, COMMIT | una scrittura confermata |
BEGIN, INSERT …, ROLLBACK | una scrittura non confermata: manca il commit |
nessun INSERT dopo il tuo add | l'add c'è ma non è partito niente: senza commit (o flush) il SQL non viene nemmeno spedito |
Per i test: pytest -v mostra quali sono rossi. Se un test di scrittura è rosso e la risposta sembra giusta, il problema è quasi sempre il commit.
Se il problema non è il codice
PostgreSQL non risponde nel terminale di pytest, connection failed: … No such file or directory, database "db_sessione" does not exist, pytest: command not found, No module named 'sqlalchemy': non è il tuo codice, è l'ambiente.
- PostgreSQL spento: Mac
brew services start postgresql@16, WSLsudo service postgresql start. - Il socket non si trova: Mac
export PGHOST=/tmp, WSLexport PGHOST=/var/run/postgresql. - Il venv è spento:
source .venv/bin/activate, dalla cartella dello zip.
Tutto il resto, con le soluzioni passo per passo, è nel Pronto soccorso; per pytest e il venv in particolare: pytest non parte, o non trova niente.