Redrock Postgres Documentation
Home Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
Edit page

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:

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

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

The Error exception

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.



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.

The Warning exception

exception psycopg.Warning

Exception raised for important warnings.

Defined for DBAPI compatibility, but never raised by psycopg.

The InterfaceError exception

exception psycopg.InterfaceError

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

The DatabaseError exception

exception psycopg.DatabaseError

Exception raised for errors that are related to the database.

The DataError exception

exception psycopg.DataError

An error caused by problems with the processed data.

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

The OperationalError exception

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.

The IntegrityError exception

exception psycopg.IntegrityError

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

An example may be a foreign key check failed.

The InternalError exception

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.

The ProgrammingError exception

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.

The NotSupportedError exception

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.

The ConnectionTimeout exception

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.

The PipelineAborted exception

exception psycopg.errors.PipelineAborted

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

Subclass of OperationalError.

Error diagnostics

The Diagnostic class

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:


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.

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:

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.

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)
02000 NoData DatabaseError
02001 NoAdditionalDynamicResultSetsReturned DatabaseError
Class 03 - SQL Statement Not Yet Complete
03000 SqlStatementNotYetComplete DatabaseError
Class 08 - Connection Exception
08000 ConnectionException OperationalError
08001 SqlclientUnableToEstablishSqlconnection OperationalError
08003 ConnectionDoesNotExist OperationalError
08004 SqlserverRejectedEstablishmentOfSqlconnection OperationalError
08006 ConnectionFailure OperationalError
08007 TransactionResolutionUnknown OperationalError
08P01 ProtocolViolation OperationalError
Class 09 - Triggered Action Exception
09000 TriggeredActionException DatabaseError
Class 0A - Feature Not Supported
0A000 FeatureNotSupported NotSupportedError
Class 0B - Invalid Transaction Initiation
0B000 InvalidTransactionInitiation DatabaseError
Class 0F - Locator Exception
0F000 LocatorException DatabaseError
0F001 InvalidLocatorSpecification DatabaseError
Class 0L - Invalid Grantor
0L000 InvalidGrantor DatabaseError
0LP01 InvalidGrantOperation DatabaseError
Class 0P - Invalid Role Specification
0P000 InvalidRoleSpecification DatabaseError
Class 0Z - Diagnostics Exception
0Z000 DiagnosticsException DatabaseError
0Z002 StackedDiagnosticsAccessedWithoutActiveHandler DatabaseError
Class 20 - Case Not Found
20000 CaseNotFound ProgrammingError
Class 21 - Cardinality Violation
21000 CardinalityViolation ProgrammingError
Class 22 - Data Exception
22000 DataException DataError
22001 StringDataRightTruncation DataError
22002 NullValueNoIndicatorParameter DataError
22003 NumericValueOutOfRange DataError
22004 NullValueNotAllowed DataError
22005 ErrorInAssignment DataError
22007 InvalidDatetimeFormat DataError
22008 DatetimeFieldOverflow DataError
22009 InvalidTimeZoneDisplacementValue DataError
2200B EscapeCharacterConflict DataError
2200C InvalidUseOfEscapeCharacter DataError
2200D InvalidEscapeOctet DataError
2200F ZeroLengthCharacterString DataError
2200G MostSpecificTypeMismatch DataError
2200H SequenceGeneratorLimitExceeded DataError
2200L NotAnXmlDocument DataError
2200M InvalidXmlDocument DataError
2200N InvalidXmlContent DataError
2200S InvalidXmlComment DataError
2200T InvalidXmlProcessingInstruction DataError
22010 InvalidIndicatorParameterValue DataError
22011 SubstringError DataError
22012 DivisionByZero DataError
22013 InvalidPrecedingOrFollowingSize DataError
22014 InvalidArgumentForNtileFunction DataError
22015 IntervalFieldOverflow DataError
22016 InvalidArgumentForNthValueFunction DataError
22018 InvalidCharacterValueForCast DataError
22019 InvalidEscapeCharacter DataError
2201B InvalidRegularExpression DataError
2201E InvalidArgumentForLogarithm DataError
2201F InvalidArgumentForPowerFunction DataError
2201G InvalidArgumentForWidthBucketFunction DataError
2201W InvalidRowCountInLimitClause DataError
2201X InvalidRowCountInResultOffsetClause DataError
22021 CharacterNotInRepertoire DataError
22022 IndicatorOverflow DataError
22023 InvalidParameterValue DataError
22024 UnterminatedCString DataError
22025 InvalidEscapeSequence DataError
22026 StringDataLengthMismatch DataError
22027 TrimError DataError
2202E ArraySubscriptError DataError
2202G InvalidTablesampleRepeat DataError
2202H InvalidTablesampleArgument DataError
22030 DuplicateJsonObjectKeyValue DataError
22031 InvalidArgumentForSqlJsonDatetimeFunction DataError
22032 InvalidJsonText DataError
22033 InvalidSqlJsonSubscript DataError
22034 MoreThanOneSqlJsonItem DataError
22035 NoSqlJsonItem DataError
22036 NonNumericSqlJsonItem DataError
22037 NonUniqueKeysInAJsonObject DataError
22038 SingletonSqlJsonItemRequired DataError
22039 SqlJsonArrayNotFound DataError
2203A SqlJsonMemberNotFound DataError
2203B SqlJsonNumberNotFound DataError
2203C SqlJsonObjectNotFound DataError
2203D TooManyJsonArrayElements DataError
2203E TooManyJsonObjectMembers DataError
2203F SqlJsonScalarRequired DataError
2203G SqlJsonItemCannotBeCastToTargetType DataError
22P01 FloatingPointException DataError
22P02 InvalidTextRepresentation DataError
22P03 InvalidBinaryRepresentation DataError
22P04 BadCopyFileFormat DataError
22P05 UntranslatableCharacter DataError
22P06 NonstandardUseOfEscapeCharacter DataError
Class 23 - Integrity Constraint Violation
23000 IntegrityConstraintViolation IntegrityError
23001 RestrictViolation IntegrityError
23502 NotNullViolation IntegrityError
23503 ForeignKeyViolation IntegrityError
23505 UniqueViolation IntegrityError
23514 CheckViolation IntegrityError
23P01 ExclusionViolation IntegrityError
Class 24 - Invalid Cursor State
24000 InvalidCursorState InternalError
Class 25 - Invalid Transaction State
25000 InvalidTransactionState InternalError
25001 ActiveSqlTransaction InternalError
25002 BranchTransactionAlreadyActive InternalError
25003 InappropriateAccessModeForBranchTransaction InternalError
25004 InappropriateIsolationLevelForBranchTransaction InternalError
25005 NoActiveSqlTransactionForBranchTransaction InternalError
25006 ReadOnlySqlTransaction InternalError
25007 SchemaAndDataStatementMixingNotSupported InternalError
25008 HeldCursorRequiresSameIsolationLevel InternalError
25P01 NoActiveSqlTransaction InternalError
25P02 InFailedSqlTransaction InternalError
25P03 IdleInTransactionSessionTimeout InternalError
Class 26 - Invalid SQL Statement Name
26000 InvalidSqlStatementName ProgrammingError
Class 27 - Triggered Data Change Violation
27000 TriggeredDataChangeViolation OperationalError
Class 28 - Invalid Authorization Specification
28000 InvalidAuthorizationSpecification OperationalError
28P01 InvalidPassword OperationalError
Class 2B - Dependent Privilege Descriptors Still Exist
2B000 DependentPrivilegeDescriptorsStillExist InternalError
2BP01 DependentObjectsStillExist InternalError
Class 2D - Invalid Transaction Termination
2D000 InvalidTransactionTermination InternalError
Class 2F - SQL Routine Exception
2F000 SqlRoutineException OperationalError
2F002 ModifyingSqlDataNotPermitted OperationalError
2F003 ProhibitedSqlStatementAttempted OperationalError
2F004 ReadingSqlDataNotPermitted OperationalError
2F005 FunctionExecutedNoReturnStatement OperationalError
Class 34 - Invalid Cursor Name
34000 InvalidCursorName ProgrammingError
Class 38 - External Routine Exception
38000 ExternalRoutineException OperationalError
38001 ContainingSqlNotPermitted OperationalError
38002 ModifyingSqlDataNotPermittedExt OperationalError
38003 ProhibitedSqlStatementAttemptedExt OperationalError
38004 ReadingSqlDataNotPermittedExt OperationalError
Class 39 - External Routine Invocation Exception
39000 ExternalRoutineInvocationException OperationalError
39001 InvalidSqlstateReturned OperationalError
39004 NullValueNotAllowedExt OperationalError
39P01 TriggerProtocolViolated OperationalError
39P02 SrfProtocolViolated OperationalError
39P03 EventTriggerProtocolViolated OperationalError
Class 3B - Savepoint Exception
3B000 SavepointException OperationalError
3B001 InvalidSavepointSpecification OperationalError
Class 3D - Invalid Catalog Name
3D000 InvalidCatalogName ProgrammingError
Class 3F - Invalid Schema Name
3F000 InvalidSchemaName ProgrammingError
Class 40 - Transaction Rollback
40000 TransactionRollback OperationalError
40001 SerializationFailure OperationalError
40002 TransactionIntegrityConstraintViolation OperationalError
40003 StatementCompletionUnknown OperationalError
40P01 DeadlockDetected OperationalError
Class 42 - Syntax Error or Access Rule Violation
42000 SyntaxErrorOrAccessRuleViolation ProgrammingError
42501 InsufficientPrivilege ProgrammingError
42601 SyntaxError ProgrammingError
42602 InvalidName ProgrammingError
42611 InvalidColumnDefinition ProgrammingError
42622 NameTooLong ProgrammingError
42701 DuplicateColumn ProgrammingError
42702 AmbiguousColumn ProgrammingError
42703 UndefinedColumn ProgrammingError
42704 UndefinedObject ProgrammingError
42710 DuplicateObject ProgrammingError
42712 DuplicateAlias ProgrammingError
42723 DuplicateFunction ProgrammingError
42725 AmbiguousFunction ProgrammingError
42803 GroupingError ProgrammingError
42804 DatatypeMismatch ProgrammingError
42809 WrongObjectType ProgrammingError
42830 InvalidForeignKey ProgrammingError
42846 CannotCoerce ProgrammingError
42883 UndefinedFunction ProgrammingError
428C9 GeneratedAlways ProgrammingError
42939 ReservedName ProgrammingError
42P01 UndefinedTable ProgrammingError
42P02 UndefinedParameter ProgrammingError
42P03 DuplicateCursor ProgrammingError
42P04 DuplicateDatabase ProgrammingError
42P05 DuplicatePreparedStatement ProgrammingError
42P06 DuplicateSchema ProgrammingError
42P07 DuplicateTable ProgrammingError
42P08 AmbiguousParameter ProgrammingError
42P09 AmbiguousAlias ProgrammingError
42P10 InvalidColumnReference ProgrammingError
42P11 InvalidCursorDefinition ProgrammingError
42P12 InvalidDatabaseDefinition ProgrammingError
42P13 InvalidFunctionDefinition ProgrammingError
42P14 InvalidPreparedStatementDefinition ProgrammingError
42P15 InvalidSchemaDefinition ProgrammingError
42P16 InvalidTableDefinition ProgrammingError
42P17 InvalidObjectDefinition ProgrammingError
42P18 IndeterminateDatatype ProgrammingError
42P19 InvalidRecursion ProgrammingError
42P20 WindowingError ProgrammingError
42P21 CollationMismatch ProgrammingError
42P22 IndeterminateCollation ProgrammingError
Class 44 - WITH CHECK OPTION Violation
44000 WithCheckOptionViolation ProgrammingError
Class 53 - Insufficient Resources
53000 InsufficientResources OperationalError
53100 DiskFull OperationalError
53200 OutOfMemory OperationalError
53300 TooManyConnections OperationalError
53400 ConfigurationLimitExceeded OperationalError
Class 54 - Program Limit Exceeded
54000 ProgramLimitExceeded OperationalError
54001 StatementTooComplex OperationalError
54011 TooManyColumns OperationalError
54023 TooManyArguments OperationalError
Class 55 - Object Not In Prerequisite State
55000 ObjectNotInPrerequisiteState OperationalError
55006 ObjectInUse OperationalError
55P02 CantChangeRuntimeParam OperationalError
55P03 LockNotAvailable OperationalError
55P04 UnsafeNewEnumValueUsage OperationalError
Class 57 - Operator Intervention
57000 OperatorIntervention OperationalError
57014 QueryCanceled OperationalError
57P01 AdminShutdown OperationalError
57P02 CrashShutdown OperationalError
57P03 CannotConnectNow OperationalError
57P04 DatabaseDropped OperationalError
57P05 IdleSessionTimeout OperationalError
Class 58 - System Error (errors external to PostgreSQL itself)
58000 SystemError OperationalError
58030 IoError OperationalError
58P01 UndefinedFile OperationalError
58P02 DuplicateFile OperationalError
Class 72 - Snapshot Failure
72000 SnapshotTooOld DatabaseError
Class F0 - Configuration File Error
F0000 ConfigFileError OperationalError
F0001 LockFileExists OperationalError
Class HV - Foreign Data Wrapper Error (SQL/MED)
HV000 FdwError OperationalError
HV001 FdwOutOfMemory OperationalError
HV002 FdwDynamicParameterValueNeeded OperationalError
HV004 FdwInvalidDataType OperationalError
HV005 FdwColumnNameNotFound OperationalError
HV006 FdwInvalidDataTypeDescriptors OperationalError
HV007 FdwInvalidColumnName OperationalError
HV008 FdwInvalidColumnNumber OperationalError
HV009 FdwInvalidUseOfNullPointer OperationalError
HV00A FdwInvalidStringFormat OperationalError
HV00B FdwInvalidHandle OperationalError
HV00C FdwInvalidOptionIndex OperationalError
HV00D FdwInvalidOptionName OperationalError
HV00J FdwOptionNameNotFound OperationalError
HV00K FdwReplyHandle OperationalError
HV00L FdwUnableToCreateExecution OperationalError
HV00M FdwUnableToCreateReply OperationalError
HV00N FdwUnableToEstablishConnection OperationalError
HV00P FdwNoSchemas OperationalError
HV00Q FdwSchemaNotFound OperationalError
HV00R FdwTableNotFound OperationalError
HV010 FdwFunctionSequenceError OperationalError
HV014 FdwTooManyHandles OperationalError
HV021 FdwInconsistentDescriptorInformation OperationalError
HV024 FdwInvalidAttributeValue OperationalError
HV090 FdwInvalidStringLengthOrBufferLength OperationalError
HV091 FdwInvalidDescriptorFieldIdentifier OperationalError
Class P0 - PL/pgSQL Error
P0000 PlpgsqlError ProgrammingError
P0001 RaiseException ProgrammingError
P0002 NoDataFound ProgrammingError
P0003 TooManyRows ProgrammingError
P0004 AssertFailure ProgrammingError
Class XX - Internal Error
XX000 InternalError_ InternalError
XX001 DataCorrupted InternalError
XX002 IndexCorrupted InternalError

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