Core Exceptions

Core Exceptions

Exceptions used with SQLAlchemy.

The base exception class is SQLAlchemyError. Exceptions which areraised as a result of DBAPI exceptions are all subclasses ofDBAPIError.

exception sqlalchemy.exc.AmbiguousForeignKeysError(*arg, **kw)
Raised when more than one foreign key matching can be locatedbetween two selectables during a join.
exception sqlalchemy.exc.ArgumentError(*arg, **kw)
Raised when an invalid or conflicting function argument is supplied.

This error generally corresponds to construction time state errors.

exception sqlalchemy.exc.CircularDependencyError(message, cycles, edges, msg=None, code=None)
Raised by topological sorts when a circular dependency is detected.

There are two scenarios where this error occurs:

In a Session flush operation, if two objects are mutually dependenton each other, they can not be inserted or deleted via INSERT orDELETE statements alone; an UPDATE will be needed to post-associateor pre-deassociate one of the foreign key constrained values.The post_update flag described at Rows that point to themselves / Mutually Dependent Rows can resolvethis cycle.
In a MetaData.sorted_tables operation, two ForeignKeyor ForeignKeyConstraint objects mutually refer to eachother. Apply the use_alter=True flag to one or both,see Creating/Dropping Foreign Key Constraints via ALTER.

exception sqlalchemy.exc.CompileError(*arg, **kw)
Raised when an error occurs during SQL compilation
exception sqlalchemy.exc.DBAPIError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Raised when the execution of a database operation fails.

Wraps exceptions raised by the DB-API underlying thedatabase operation. Driver-specific implementations of the standardDB-API exception types are wrapped by matching sub-types of SQLAlchemy’sDBAPIError when possible. DB-API’s Error type maps toDBAPIError in SQLAlchemy, otherwise the names are identical. Notethat there is no guarantee that different DB-API implementations willraise the same exception type for any given error condition.

DBAPIError features statementand params attributes which supply contextregarding the specifics of the statement which had an issue, for thetypical case when the error was raised within the context ofemitting a SQL statement.

The wrapped exception object is available in theorig attribute. Its type and properties areDB-API implementation specific.

exception sqlalchemy.exc.DataError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API DataError.
exception sqlalchemy.exc.DatabaseError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API DatabaseError.
exception sqlalchemy.exc.DisconnectionError(*arg, **kw)
A disconnect is detected on a raw DB-API connection.

This error is raised and consumed internally by a connection pool. It canbe raised by the PoolEvents.checkout() event so that the host poolforces a retry; the exception will be caught three times in a row beforethe pool gives up and raises InvalidRequestErrorregarding the connection attempt.

class sqlalchemy.exc.DontWrapMixin
A mixin class which, when applied to a user-defined Exception class,will not be wrapped inside of StatementError if the error isemitted within the process of executing a statement.

E.g.:

from sqlalchemy.exc import DontWrapMixin
 
class MyCustomException(Exception, DontWrapMixin):
    pass
 
class MySpecialType(TypeDecorator):
    impl = String
 
    def process_bind_param(self, value, dialect):
        if value == 'invalid':
            raise MyCustomException("invalid!")

exception sqlalchemy.exc.IdentifierError(*arg, **kw)
Raised when a schema name is beyond the max character limit
exception sqlalchemy.exc.IntegrityError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API IntegrityError.
exception sqlalchemy.exc.InterfaceError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API InterfaceError.
exception sqlalchemy.exc.InternalError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API InternalError.
exception sqlalchemy.exc.InvalidRequestError(*arg, **kw)
SQLAlchemy was asked to do something it can’t do.

This error generally corresponds to runtime state errors.

exception sqlalchemy.exc.InvalidatePoolError(*arg, **kw)
Raised when the connection pool should invalidate all stale connections.

A subclass of DisconnectionError that indicates that thedisconnect situation encountered on the connection probably means theentire pool should be invalidated, as the database has been restarted.

This exception will be handled otherwise the same way asDisconnectionError, allowing three attempts to reconnectbefore giving up.

New in version 1.2.

exception sqlalchemy.exc.NoForeignKeysError(*arg, **kw)
Raised when no foreign keys can be located between two selectablesduring a join.
exception sqlalchemy.exc.NoInspectionAvailable(*arg, **kw)
A subject passed to sqlalchemy.inspection.inspect() producedno context for inspection.
exception sqlalchemy.exc.NoReferenceError(*arg, **kw)
Raised by ForeignKey to indicate a reference cannot be resolved.
exception sqlalchemy.exc.NoReferencedColumnError(message, tname, cname)
Raised by ForeignKey when the referred Column cannot belocated.
exception sqlalchemy.exc.NoReferencedTableError(message, tname)
Raised by ForeignKey when the referred Table cannot belocated.
exception sqlalchemy.exc.NoSuchColumnError
A nonexistent column is requested from a RowProxy.
exception sqlalchemy.exc.NoSuchModuleError(*arg, **kw)
Raised when a dynamically-loaded module (usually a database dialect)of a particular name cannot be located.
exception sqlalchemy.exc.NoSuchTableError(*arg, **kw)
Table does not exist or is not visible to a connection.
exception sqlalchemy.exc.NotSupportedError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API NotSupportedError.
exception sqlalchemy.exc.ObjectNotExecutableError(target)
Raised when an object is passed to .execute() that can’t beexecuted as SQL.

New in version 1.1.

exception sqlalchemy.exc.OperationalError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API OperationalError.
exception sqlalchemy.exc.ProgrammingError(statement, params, orig, hide_parameters=False, connection_invalidated=False, code=None, ismulti=None)
Wraps a DB-API ProgrammingError.
exception sqlalchemy.exc.ResourceClosedError(*arg, **kw)
An operation was requested from a connection, cursor, or otherobject that’s in a closed state.
exception sqlalchemy.exc.SADeprecationWarning
Issued once per usage of a deprecated API.
exception sqlalchemy.exc.SAPendingDeprecationWarning
Issued once per usage of a deprecated API.
exception sqlalchemy.exc.SAWarning
Issued at runtime.
exception sqlalchemy.exc.SQLAlchemyError(*arg, **kw)
Generic error class.
exception sqlalchemy.exc.StatementError(message, statement, params, orig, hide_parameters=False, code=None, ismulti=None)
An error occurred during execution of a SQL statement.

StatementError wraps the exception raisedduring execution, and features statementand params attributes which supply context regardingthe specifics of the statement which had an issue.

The wrapped exception object is available inthe orig attribute.

orig = None
The DBAPI exception object.
params = None
The parameter list being used when this exception occurred.
statement = None
The string SQL statement being invoked when this exception occurred.

exception sqlalchemy.exc.TimeoutError(*arg, **kw)
Raised when a connection pool times out on getting a connection.
exception sqlalchemy.exc.UnboundExecutionError(*arg, **kw)
SQL was attempted without a database connection to execute it on.
exception sqlalchemy.exc.UnreflectableTableError(*arg, **kw)
Table exists but can’t be reflected for some reason.

New in version 1.2.

exception sqlalchemy.exc.UnsupportedCompilationError(compiler, element_type)
Raised when an operation is not supported by the given compiler.