sqlalchemy.orm.exc.DetachedInstanceError: instance is not bound to a Session

What this error actually means

An ORM instance is not a plain data object. It is a proxy with a live link to the `Session` that loaded it, and unloaded attributes — lazy relationships, deferred columns, anything expired — are fetched on first access through that link. This error means the link is gone and something just asked for a value that only the database has.

The detail that makes this feel arbitrary is `expire_on_commit`, which defaults to `True`. On commit, every loaded attribute on every instance in the session is marked expired, so the *next* attribute access triggers a refresh query. Inside the session that is invisible — it just costs a query. Outside it, every attribute access on the object raises, including ones you already read successfully a line earlier. Same object, same field, different outcome, entirely determined by whether the session is still open.

So the error is never really about the attribute in the traceback. It is a boundary violation: an object crossed out of the unit of work that owns it while still depending on that unit of work. The fix is to decide what crosses the boundary — data, or a live proxy — and make that explicit.

How to diagnose it

from sqlalchemy import inspect
st = inspect(order)
print(st.detached, st.expired, st.unloaded)

create_engine(dsn, echo=True)   # or logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)

The fix

Decide the boundary and return data across it, not proxies. Convert entities to plain objects — a dataclass, a Pydantic model built with `model_validate`, a dict — *inside* the session scope, and let only those leave. This is the fix that removes the whole class of bug rather than the current instance of it, because it makes the dependency on the session lexically obvious.

If entities must cross the boundary, load everything they will need eagerly and explicitly. `selectinload` for collections (one extra query, no row multiplication), `joinedload` for many-to-one (single query, but fans out rows on collections). Choosing the strategy per relationship at the query site is better than setting `lazy="joined"` on the model, which pulls the whole graph into every unrelated query.

Understand `expire_on_commit=False` before reaching for it. It stops the post-commit expiry, so already-loaded scalar attributes stay readable after commit and after detachment. It does not load relationships that were never loaded, and it means your objects may hold stale values that no longer match the database. It is a reasonable choice for short request-scoped sessions and a poor one for long-lived ones.

Never pass ORM instances to another thread, to Celery, or into a cache. Pass the primary key and reload inside that worker’s own session — that is also what makes the task retryable, since it then reads current state rather than a snapshot from whenever the task was queued.

For a genuine need to reattach, `session.merge(instance)` copies state into a new session and returns the attached copy. Treat it as a deliberate operation with a cost, not as a repair for a leaked object, and be aware it will emit a SELECT unless you pass `load=False` under conditions you fully control.

# Raises when FastAPI serialises order.items after the scope exits
@app.get("/orders/{order_id}")
def get_order(order_id: int) -> OrderOut:
    with Session(engine) as session:
        return session.get(Order, order_id)

# Load what the response needs, convert inside the scope, return data
@app.get("/orders/{order_id}")
def get_order(order_id: int) -> OrderOut:
    with Session(engine) as session:
        stmt = (
            select(Order)
            .options(selectinload(Order.items), joinedload(Order.customer))
            .where(Order.id == order_id)
        )
        order = session.execute(stmt).unique().scalar_one()
        return OrderOut.model_validate(order, from_attributes=True)

How to stop it coming back

• Make the rule explicit in review: ORM entities never leave the session scope — response models and dataclasses do
• Pass identifiers, never instances, to Celery tasks and thread pools; this also makes tasks safely retryable
• Assert query counts in tests for hot endpoints; a lazy-loading regression shows up as a count change before it shows up as this exception
• Prefer explicit `selectinload`/`joinedload` at the call site over `lazy=` defaults on models, so each query loads exactly what it needs
• Treat caching an ORM object as a review blocker — cache the serialised form

FAQ

Related

Other errors engineers hit next to this one

• CORS preflight: missing Access-Control-Allow-Origin
• 413 Payload Too Large
• 429 Too Many Requests and Retry-After
• nginx 499 client closed request
• upstream prematurely closed connection
• Intermittent 502 after an idle keep-alive connection
• SSL certificate problem: unable to get local issuer certificate
• ERR_INCOMPLETE_CHUNKED_ENCODING