ORM Exceptions — SQLAlchemy 2.0 Documentation

Release: 2.0.49 | Release Date: April 3, 2026

# SQLAlchemy 2.0 Documentation

# ORM Exceptions

SQLAlchemy ORM exceptions.

Object Name | Description
--- | ---
ConcurrentModificationError | alias of `StaleDataError`
NO_STATE | Exception types that may be raised by instrumentation implementations.

attribute `sqlalchemy.orm.exc..`sqlalchemy.orm.exc.ConcurrentModificationError

  alias of `StaleDataError`

exception sqlalchemy.orm.exc.DetachedInstanceError

  inherits from `sqlalchemy.exc.SQLAlchemyError`

  An attempt to access unloaded attributes on a mapped instance that is detached.

exception sqlalchemy.orm.exc.FlushError

  inherits from `sqlalchemy.exc.SQLAlchemyError`

  A invalid condition was detected during flush().

exception sqlalchemy.orm.exc.LoaderStrategyException

  inherits from `sqlalchemy.exc.InvalidRequestError`

  A loader strategy for an attribute does not exist.

  method `sqlalchemy.orm.exc.LoaderStrategyException.` __init__(applied_to_property_type: Type[Any], requesting_property: MapperProperty[Any], applies_to: Type[MapperProperty[Any]] | None, actual_strategy_type: Type[LoaderStrategy] | None, strategy_key: Tuple[Any, ...])

exception sqlalchemy.orm.exc.MappedAnnotationError

  inherits from `sqlalchemy.exc.ArgumentError`

  Raised when ORM annotated declarative cannot interpret the expression present inside of the `Mapped` construct.

  Added in version 2.0.40.

sqlalchemy.orm.exc.NO_STATE = (<class 'AttributeError'>, <class 'KeyError'>)

  Exception types that may be raised by instrumentation implementations.

exception sqlalchemy.orm.exc.ObjectDeletedError

  inherits from `sqlalchemy.exc.InvalidRequestError`

  A refresh operation failed to retrieve the database row corresponding to an object’s known primary key identity.

  A refresh operation proceeds when an expired attribute is accessed on an object, or when `Query.get()` is used to retrieve an object which is, upon retrieval, detected as expired. A SELECT is emitted for the target row based on primary key; if no row is returned, this exception is raised.

  The true meaning of this exception is simply that no row exists for the primary key identifier associated with a persistent object. The row may have been deleted, or in some cases the primary key updated to a new value, outside of the ORM’s management of the target object.

  method `sqlalchemy.orm.exc.ObjectDeletedError.` __init__(state: InstanceState[Any], msg: str | None = None)

exception sqlalchemy.orm.exc.ObjectDereferencedError

  inherits from `sqlalchemy.exc.SQLAlchemyError`

  An operation cannot complete due to an object being garbage collected.

exception sqlalchemy.orm.exc.StaleDataError

  inherits from `sqlalchemy.exc.SQLAlchemyError`

  An operation encountered database state that is unaccounted for.

  Conditions which cause this to happen include:

  - A flush may have attempted to update or delete rows and an unexpected number of rows were matched during the UPDATE or DELETE statement. Note that when version_id_col is used, rows in UPDATE or DELETE statements are also matched against the current known version identifier.

  - A mapped object with version_id_col was refreshed, and the version number coming back from the database does not match that of the object itself.

  - A object is detached from its parent object, however the object was previously attached to a different parent identity which was garbage collected, and a decision cannot be made if the new parent was really the most recent “parent”.

exception sqlalchemy.orm.exc.UnmappedClassError

  inherits from `sqlalchemy.orm.exc.UnmappedError`

  An mapping operation was requested for an unknown class.

  method `sqlalchemy.orm.exc.UnmappedClassError.` __init__(cls: Type[_T], msg: str | None = None)

exception sqlalchemy.orm.exc.UnmappedColumnError

  inherits from `sqlalchemy.exc.InvalidRequestError`

  Mapping operation was requested on an unknown column.

exception sqlalchemy.orm.exc.UnmappedError

  inherits from `sqlalchemy.exc.InvalidRequestError`

  Base for exceptions that involve expected mappings not present.

exception sqlalchemy.orm.exc.UnmappedInstanceError

  inherits from `sqlalchemy.orm.exc.UnmappedError`

  An mapping operation was requested for an unknown instance.

  method `sqlalchemy.orm.exc.UnmappedInstanceError.` __init__(obj: object, msg: str | None = None)