errors – Package exceptions#
This module exposes objects to represent and examine database errors.
DB-API exceptions#
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
exceptstatement.This exception is guaranteed to be picklable.
- diag#
A
Diagnosticobject to inspect details of the errors from the database.
- sqlstate: str | None = 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: pq.PGconn | None#
The connection object, if the error was raised from a connection attempt.
It has been closed and will be in
BADstate; however it might be useful to verify precisely what went wrong, for instance checking theneeds_passwordandused_passwordattributes. Attempting to operate this connection will raise anOperationalError.New in version 3.1.
- pgresult: pq.PGresult | None#
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.
Other Psycopg errors#
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_timeoutis specified and a connection is not obtained in useful time.Subclass of
OperationalError.
- exception psycopg.errors.CancellationTimeout#
Exception raised on timeout of connection’s
cancel_safe()method.Subclass of
OperationalError.
- exception psycopg.errors.PipelineAborted#
Raised when a operation fails because the current pipeline is in aborted state.
Subclass of
OperationalError.
Error diagnostics#
- class psycopg.errors.Diagnostic#
Details from a database error report.
The object is available as the
Error.diagattribute and is passed to the callback functions registered withadd_notice_handler().All the information available from the
PQresultErrorField()function are exposed as attributes by the object. For instance theseverityattribute returns thePG_DIAG_SEVERITYcode. 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;
Noneif 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.
SQLSTATE exceptions#
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[psycopg.Error]#
Lookup an error code or constant name and return its exception class.
Raise
KeyErrorif 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
List of known exceptions#
The following are all the SQLSTATE-related error classed defined by this module, together with the base DBAPI exception they derive from.
SQLSTATE |
Exception |
Base exception |
|---|---|---|
Class 02 - No Data (this is also a warning class per the SQL standard) |
||
|
|
|
|
|
|
Class 03 - SQL Statement Not Yet Complete |
||
|
|
|
Class 08 - Connection Exception |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 09 - Triggered Action Exception |
||
|
|
|
Class 0A - Feature Not Supported |
||
|
|
|
Class 0B - Invalid Transaction Initiation |
||
|
|
|
Class 0F - Locator Exception |
||
|
|
|
|
|
|
Class 0L - Invalid Grantor |
||
|
|
|
|
|
|
Class 0P - Invalid Role Specification |
||
|
|
|
Class 0Z - Diagnostics Exception |
||
|
|
|
|
|
|
Class 20 - Case Not Found |
||
|
|
|
Class 21 - Cardinality Violation |
||
|
|
|
Class 22 - Data Exception |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 23 - Integrity Constraint Violation |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 24 - Invalid Cursor State |
||
|
|
|
Class 25 - Invalid Transaction State |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 26 - Invalid SQL Statement Name |
||
|
|
|
Class 27 - Triggered Data Change Violation |
||
|
|
|
Class 28 - Invalid Authorization Specification |
||
|
|
|
|
|
|
Class 2B - Dependent Privilege Descriptors Still Exist |
||
|
|
|
|
|
|
Class 2D - Invalid Transaction Termination |
||
|
|
|
Class 2F - SQL Routine Exception |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 34 - Invalid Cursor Name |
||
|
|
|
Class 38 - External Routine Exception |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 39 - External Routine Invocation Exception |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 3B - Savepoint Exception |
||
|
|
|
|
|
|
Class 3D - Invalid Catalog Name |
||
|
|
|
Class 3F - Invalid Schema Name |
||
|
|
|
Class 40 - Transaction Rollback |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 42 - Syntax Error or Access Rule Violation |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 44 - WITH CHECK OPTION Violation |
||
|
|
|
Class 53 - Insufficient Resources |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 54 - Program Limit Exceeded |
||
|
|
|
|
|
|
|
|
|
|
|
|
Class 55 - Object Not In Prerequisite State |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 57 - Operator Intervention |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class 58 - System Error (errors external to PostgreSQL itself) |
||
|
|
|
|
|
|
|
|
|
|
|
|
Class 72 - Snapshot Failure |
||
|
|
|
Class F0 - Configuration File Error |
||
|
|
|
|
|
|
Class HV - Foreign Data Wrapper Error (SQL/MED) |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class P0 - PL/pgSQL Error |
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Class XX - Internal Error |
||
|
|
|
|
|
|
|
|
|
New in version 3.1.4: Exception SqlJsonItemCannotBeCastToTargetType, introduced in PostgreSQL 15.
New in version 3.2.3: Exception TransactionTimeout, introduced in PostgreSQL 17.