errors – Package exceptions

This module exposes objects to represent and examine database errors.

In compliance with the DB-API, all the exceptions raised by Psycopg derive from the following classes:

Exception
|__ Warning
|__ Error
    |__ InterfaceError
    |__ DatabaseError
        |__ DataError
        |__ OperationalError
        |__ IntegrityError
        |__ InternalError
        |__ ProgrammingError
        |__ NotSupportedError

These classes are exposed both by this module and the root psycopg module.

exception psycopg.Error

Base exception for all the errors psycopg will raise.

Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement.

This exception is guaranteed to be picklable.

diag

A Diagnostic object to inspect details of the errors from the database.

sqlstate: Optional[str] = None

The code of the error, if received from the server.

This attribute is also available as class attribute on the SQLSTATE exceptions classes.

pgconn: Optional[pq.PGconn]

The connection object, if the error was raised from a connection attempt.

It has been closed and will be in BAD state; however it might be useful to verify precisely what went wrong, for instance checking the needs_password and used_password attributes. Attempting to operate this connection will raise an OperationalError.

New in version 3.1.

pgresult: Optional[pq.PGresult]

The result object, if the exception was raised after a failed query.

New in version 3.1.

exception psycopg.Warning

Exception raised for important warnings.

Defined for DBAPI compatibility, but never raised by psycopg.

exception psycopg.InterfaceError

An error related to the database interface rather than the database itself.

exception psycopg.DatabaseError

Exception raised for errors that are related to the database.

exception psycopg.DataError

An error caused by problems with the processed data.

Examples may be division by zero, numeric value out of range, etc.

exception psycopg.OperationalError

An error related to the database’s operation.

These errors are not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.

exception psycopg.IntegrityError

An error caused when the relational integrity of the database is affected.

An example may be a foreign key check failed.

exception psycopg.InternalError

An error generated when the database encounters an internal error,

Examples could be the cursor is not valid anymore, the transaction is out of sync, etc.

exception psycopg.ProgrammingError

Exception raised for programming errors

Examples may be table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc.

exception psycopg.NotSupportedError

A method or database API was used which is not supported by the database.

In addition to the standard DB-API errors, Psycopg defines a few more specific ones.

exception psycopg.errors.ConnectionTimeout

Exception raised on timeout of the connect() method.

The error is raised if the connect_timeout is specified and a connection is not obtained in useful time.

Subclass of OperationalError.

exception psycopg.errors.PipelineAborted

Raised when a operation fails because the current pipeline is in aborted state.

Subclass of OperationalError.

class psycopg.errors.Diagnostic

Details from a database error report.

The object is available as the Error.diag attribute and is passed to the callback functions registered with add_notice_handler().

All the information available from the PQresultErrorField() function are exposed as attributes by the object. For instance the severity attribute returns the PG_DIAG_SEVERITY code. Please refer to the PostgreSQL documentation for the meaning of all the attributes.

The attributes available are:

column_name

constraint_name

context

datatype_name

internal_position

internal_query

message_detail

message_hint

message_primary

schema_name

severity

severity_nonlocalized

source_file

source_function

source_line

sqlstate

statement_position

table_name

A string with the error field if available; None if not available. The attribute value is available only for errors sent by the server: not all the fields are available for all the errors and for all the server versions.

Errors coming from a database server (as opposite as ones generated client-side, such as connection failed) usually have a 5-letters error code called SQLSTATE (available in the sqlstate attribute of the error’s diag attribute).

Psycopg exposes a different class for each SQLSTATE value, allowing to write idiomatic error handling code according to specific conditions happening in the database:

try:
    cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
except psycopg.errors.LockNotAvailable:
    locked = True

The exception names are generated from the PostgreSQL source code and includes classes for every error defined by PostgreSQL in versions between 9.6 and 15. Every class in the module is named after what referred as “condition name” in the documentation, converted to CamelCase: e.g. the error 22012, division_by_zero is exposed by this module as the class DivisionByZero. There is a handful of… exceptions to this rule, required for disambiguate name clashes: please refer to the table below for all the classes defined.

Every exception class is a subclass of one of the standard DB-API exception, thus exposing the Error interface.

Changed in version 3.1.4: Added exceptions introduced in PostgreSQL 15.

psycopg.errors.lookup(sqlstate: str) → Type[Error]

Lookup an error code or constant name and return its exception class.

Raise KeyError if the code is not found.

Example: if you have code using constant names or sql codes you can use them to look up the exception class.

try:
    cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
except psycopg.errors.lookup("UNDEFINED_TABLE"):
    missing = True
except psycopg.errors.lookup("55P03"):
    locked = True

The following are all the SQLSTATE-related error classed defined by this module, together with the base DBAPI exception they derive from.

New in version 3.1.4: Exception SqlJsonItemCannotBeCastToTargetType, introduced in PostgreSQL 15.