Exceptions (quantum_safe.exceptions)

All exceptions inherit from QuantumSafeError so you can catch the entire hierarchy with a single except clause. Every exception carries a machine-readable code string for programmatic handling.

Exception hierarchy

QuantumSafeError
├── CryptoError
│   ├── VerificationError
│   ├── DecapsulationError
│   └── KeyGenerationError
├── SerializationError
│   ├── KeyParseError
│   └── IncompatibleKeyVersion
├── BackendError
│   └── BackendNotAvailable
├── ConfigurationError
│   └── UnsupportedAlgorithm
├── MigrationError
│   └── ClassicalKeyDetected
└── InsecureOperationError

Reference

exception quantum_safe.exceptions.QuantumSafeError(message, **context)

Base class for all quantum-safe library errors.

Parameters:

• message (str)

• context (Any)

exception quantum_safe.exceptions.CryptoError(message, **context)

Raised when a cryptographic operation fails.

Parameters:

• message (str)

• context (Any)

exception quantum_safe.exceptions.VerificationError(algo=None, context_mismatch=False)

Signature verification failed.

Parameters:

• algo (str | None)

• context_mismatch (bool)

exception quantum_safe.exceptions.DecapsulationError(algo=None)

Decapsulation failed — usually means wrong secret key or tampered ciphertext.

Do NOT log ciphertexts or key material when catching this; the failure itself is the only safe thing to propagate.

Parameters:

algo (str | None)

exception quantum_safe.exceptions.KeyGenerationError(message, **context)

Key generation failed — usually an RNG or backend issue.

Parameters:

• message (str)

• context (Any)

exception quantum_safe.exceptions.SerializationError(message, **context)

Raised when key/ciphertext serialization or deserialization fails.

Parameters:

• message (str)

• context (Any)

exception quantum_safe.exceptions.KeyParseError(fmt, reason, field=None)

Failed to parse a key from PEM, DER, CBOR, or JWK.

field indicates which part of the structure was malformed, if known.

Parameters:

• fmt (str)

• reason (str)

• field (str | None)

exception quantum_safe.exceptions.IncompatibleKeyVersion(key_version, supported_max)

The key’s qs-version field is not supported by this library version.

Parameters:

• key_version (int)

• supported_max (int)

exception quantum_safe.exceptions.BackendError(message, **context)

Errors related to cryptographic backend selection or execution.

Parameters:

• message (str)

• context (Any)

exception quantum_safe.exceptions.BackendNotAvailable(backend)

A required backend is not installed or could not be loaded.

The install_hint attribute contains a pip command the user can run to fix the problem.

Parameters:

backend (str)

exception quantum_safe.exceptions.ConfigurationError(message, **context)

Raised when the library is misconfigured.

Parameters:

• message (str)

• context (Any)

exception quantum_safe.exceptions.UnsupportedAlgorithm(algo, available=None)

The requested algorithm is not supported.

available contains the list of valid algorithm names so callers can suggest alternatives without hard-coding the list.

Parameters:

• algo (str)

• available (list[str] | None)

exception quantum_safe.exceptions.MigrationError(message, **context)

Errors raised during key migration or classical-crypto scanning.

Parameters:

• message (str)

• context (Any)

exception quantum_safe.exceptions.ClassicalKeyDetected(algo, min_required='hybrid')

A pure classical (non-hybrid) key was used where PQC is required.

This is raised in strict mode when a classical-only key is passed to an operation that requires at least hybrid security.

Parameters:

• algo (str)

• min_required (str)

exception quantum_safe.exceptions.InsecureOperationError(message, **context)

Attempted operation is insecure and has been blocked.

Examples: - Using an algorithm below the required security level - Disabling hybrid mode without an explicit override - Reusing a nonce in a scheme that prohibits it

Parameters:

• message (str)

• context (Any)