Exceptions¶

from sqlspec.exceptions import (
    CheckViolationError,
    DatabaseConnectionError,
    DataError,
    DeadlockError,
    ForeignKeyViolationError,
    ImproperConfigurationError,
    IntegrityError,
    MigrationError,
    MissingDependencyError,
    MultipleResultsFoundError,
    NotFoundError,
    NotNullViolationError,
    OperationalError,
    PermissionDeniedError,
    QueryTimeoutError,
    SerializationConflictError,
    SQLSpecError,
    StackExecutionError,
    TransactionError,
    UniqueViolationError,
    map_sqlstate_to_exception,
)

Normalized exception hierarchy raised across all 20 database drivers, query builders, SQL file loaders, migrations, and storage pipelines.

Base & Configuration Exceptions¶

SQLSpecError ¶

Bases: Exception

Base exception class for SQLSpec exceptions.

ImproperConfigurationError ¶

Bases: SQLSpecError

Raised when configuration is invalid or incomplete.

ConfigResolverError ¶

Bases: SQLSpecError

Exception raised when config resolution fails.

MissingDependencyError ¶

Bases: SQLSpecError

Raised when a required dependency is not installed.

DialectNotSupportedError ¶

Bases: SQLBuilderError

Raised when a SQL dialect does not support a specific feature.

Integrity & Constraint Violations¶

IntegrityError ¶

Bases: RepositoryError

Data integrity error.

UniqueViolationError ¶

Bases: IntegrityError

A unique constraint was violated.

ForeignKeyViolationError ¶

Bases: IntegrityError

A foreign key constraint was violated.

NotNullViolationError ¶

Bases: IntegrityError

A not-null constraint was violated.

CheckViolationError ¶

Bases: IntegrityError

A check constraint was violated.

Execution, Concurrency & Operational Errors¶

OperationalError ¶

Bases: SQLSpecError

Operational database error (timeout, disk full, resource limit).

DatabaseConnectionError ¶

Bases: SQLSpecError

Database connection error (invalid credentials, network failure, etc.).

ConnectionTimeoutError ¶

Bases: DatabaseConnectionError

Database connection attempt timed out.

Raised when

TCP connection timeout to database server
DNS resolution timeout
SSL/TLS handshake timeout
Oracle connect timeout (ORA-12170)

QueryTimeoutError ¶

Bases: OperationalError

Query execution exceeded a timeout or deadline.

Raised when

Lock wait timeout exceeded (MySQL 1205)
Statement or service deadline exceeded

OperationCancelledError ¶

Bases: OperationalError

Database operation was explicitly cancelled by a caller or operator.

PermissionDeniedError ¶

Bases: DatabaseConnectionError

Database access denied due to insufficient privileges.

Raised when

User lacks privileges for the operation (SQLSTATE 42501)
Invalid credentials provided (SQLSTATE 28000/28P01)
Database access denied (MySQL 1044/1045/1142)
Oracle insufficient privileges (ORA-01031)

TransactionError ¶

Bases: SQLSpecError

Transaction error (rollback, deadlock, serialization failure).

SerializationConflictError ¶

Bases: TransactionError

Serialization conflict (SQLSTATE 40001) requiring retry.

DeadlockError ¶

Bases: TransactionError

Deadlock detected during transaction execution.

Raised when

PostgreSQL deadlock detected (SQLSTATE 40P01)
MySQL deadlock detected (Error 1213)
Oracle deadlock detected (ORA-00060)
SQLite database locked (SQLITE_LOCKED)

Applications should typically retry the transaction when this error occurs.

DataError ¶

Bases: SQLSpecError

Invalid data type or format for database operation.

InvalidCursorError ¶

Bases: SQLSpecError

Raised when a pagination cursor is malformed, tampered with, or mismatched.

NotFoundError ¶

Bases: RepositoryError

An identity does not exist.

MultipleResultsFoundError ¶

Bases: RepositoryError

A single database result was required but more than one were found.

RepositoryError ¶

Bases: SQLSpecError

Base repository exception type.

StackExecutionError ¶

Bases: SQLSpecError

Raised when a statement stack operation fails.

SQL Parsing, File Loader, Migration & Storage Errors¶

SQLParsingError ¶

Bases: SQLSpecError

Issues parsing SQL statements.

SQLConversionError ¶

Bases: SQLSpecError

Issues converting SQL statements.

SQLBuilderError ¶

Bases: SQLSpecError

Issues Building or Generating SQL statements.

SQLFileNotFoundError ¶

Bases: SQLSpecError

Raised when a SQL file cannot be found.

SQLFileParseError ¶

Bases: SQLSpecError

Raised when a SQL file cannot be parsed.

SQLStatementNotFoundError ¶

Bases: SQLFileNotFoundError

Raised when a named SQL statement is not loaded.

SQLFragmentNotFoundError ¶

Bases: SQLStatementNotFoundError

Raised when a SQL fragment named by an include or lookup is not loaded.

SQLSlotError ¶

Bases: SQLSpecError

Raised when a SQL statement slot is missing, unknown, or conflicts.

MigrationError ¶

Bases: SQLSpecError

Base exception for migration-related errors.

OutOfOrderMigrationError ¶

Bases: MigrationError

Raised when an out-of-order migration is detected in strict mode.

Out-of-order migrations occur when a pending migration has a timestamp earlier than already-applied migrations, typically from late-merging branches.

SquashValidationError ¶

Bases: MigrationError

Raised when migration squash validation fails.

Squash validation errors occur when

Version range is invalid (start > end)
Gap detected in version sequence
Mixed migration types that cannot be squashed
Target file already exists

StorageOperationFailedError ¶

Bases: SQLSpecError

Raised when a storage backend operation fails.

FileNotFoundInStorageError ¶

Bases: StorageOperationFailedError

Raised when a file or object is not found in the storage backend.

StorageCapabilityError ¶

Bases: SQLSpecError

Raised when a requested storage bridge capability is unavailable.

StoragePathTraversalError ¶

Bases: StorageOperationFailedError

Raised when a storage path would resolve outside its backend root.

EventChannelError ¶

Bases: SQLSpecError

Raised when event channel operations fail.

SQLSTATE Mapping Helper¶

SQLSTATE_EXCEPTION_MAP maps standard 5-character ANSI/PostgreSQL SQLSTATE codes ("23505", "40001", "40P01", "57014", etc.) to their corresponding SQLSpecError subclass.

map_sqlstate_to_exception ¶

map_sqlstate_to_exception(sqlstate)

Map a SQLSTATE code to a SQLSpec exception class.

Checks in order of specificity

Exact 5-character match
2-character class match

Parameters:

Name	Type	Description	Default
`sqlstate`	`str \| None`	5-character SQLSTATE code	required

Returns:

Type	Description
`type[SQLSpecError] \| None`	Matching exception class or None if not mapped