kdbxtool.exceptions¶

Custom exception hierarchy for kdbxtool.

This module provides a rich exception hierarchy for better error handling and user feedback. All exceptions inherit from KdbxError.

Exception Hierarchy:: KdbxError (base) ├── FormatError │ ├── InvalidSignatureError │ ├── UnsupportedVersionError │ └── CorruptedDataError ├── CryptoError │ ├── DecryptionError │ ├── AuthenticationError │ ├── KdfError │ ├── UnknownCipherError │ └── TwofishNotAvailableError ├── CredentialError │ ├── InvalidPasswordError │ ├── InvalidKeyFileError │ ├── MissingCredentialsError │ └── YubiKeyError │ ├── YubiKeyNotFoundError │ ├── YubiKeySlotError │ ├── YubiKeyTimeoutError │ └── YubiKeyNotAvailableError └── DatabaseError

├── EntryNotFoundError └── GroupNotFoundError
Security Note:: Exception messages are designed to avoid leaking sensitive information. They provide enough context for debugging without exposing secrets.

Exceptions

`AuthenticationError`([message])	HMAC or integrity verification failed.
`CorruptedDataError`	Database file is corrupted or truncated.
`CredentialError`	Error with database credentials.
`CryptoError`	Error in cryptographic operations.
`DatabaseError`	Error in database operations.
`DecryptionError`([message])	Failed to decrypt database content.
`EntryNotFoundError`([message])	Entry not found in database.
`FormatError`	Error in KDBX file format or structure.
`GroupNotFoundError`([message])	Group not found in database.
`InvalidKeyFileError`([message])	Invalid or missing keyfile.
`InvalidPasswordError`([message])	Invalid or missing password.
`InvalidSignatureError`	Invalid KDBX file signature (magic bytes).
`InvalidXmlError`([message])	Invalid or malformed XML payload.
`Kdbx3UpgradeRequired`()	KDBX3 database requires explicit upgrade confirmation.
`KdbxError`	Base exception for all kdbxtool errors.
`KdfError`	Error in key derivation function.
`MergeError`([message])	Error during database merge operation.
`MissingCredentialsError`()	No credentials provided.
`TwofishNotAvailableError`()	Twofish cipher requested but oxifish package not installed.
`UnknownCipherError`(cipher_uuid)	Unknown or unsupported cipher algorithm.
`UnsupportedVersionError`(version_major, ...)	Unsupported KDBX version.
`YubiKeyError`	Error communicating with YubiKey.
`YubiKeyNotAvailableError`()	YubiKey support requested but yubikey-manager not installed.
`YubiKeyNotFoundError`([message])	No YubiKey detected.
`YubiKeySlotError`(slot)	YubiKey slot not configured for HMAC-SHA1.
`YubiKeyTimeoutError`([timeout_seconds])	YubiKey operation timed out.

exception kdbxtool.exceptions.KdbxError[source]¶

Bases: Exception

Base exception for all kdbxtool errors.

All exceptions raised by kdbxtool inherit from this class, making it easy to catch all library-specific errors.

exception kdbxtool.exceptions.FormatError[source]¶

Bases: KdbxError

Error in KDBX file format or structure.

Raised when the file doesn’t conform to the KDBX specification.

exception kdbxtool.exceptions.InvalidSignatureError[source]¶

Bases: FormatError

Invalid KDBX file signature (magic bytes).

The file doesn’t start with the expected KDBX magic bytes, indicating it’s not a valid KeePass database file.

exception kdbxtool.exceptions.UnsupportedVersionError(version_major, version_minor)[source]¶

Bases: FormatError

Unsupported KDBX version.

The file uses a KDBX version that this library doesn’t support.

Parameters:

version_major (int)
version_minor (int)

Return type:

None

__init__(version_major, version_minor)[source]¶

Parameters:

version_major (int)
version_minor (int)

Return type:

None

exception kdbxtool.exceptions.CorruptedDataError[source]¶

Bases: FormatError

Database file is corrupted or truncated.

The file structure is invalid, possibly due to incomplete download, disk corruption, or other data integrity issues.

exception kdbxtool.exceptions.CryptoError[source]¶

Bases: KdbxError

Error in cryptographic operations.

Base class for all cryptographic errors including encryption, decryption, and key derivation.

exception kdbxtool.exceptions.DecryptionError(message='Decryption failed')[source]¶

Bases: CryptoError

Failed to decrypt database content.

This typically indicates wrong credentials (password/keyfile), but the message is kept generic to avoid confirming which credential component is incorrect.

Parameters:: message (str)
Return type:: None

__init__(message='Decryption failed')[source]¶

Parameters:: message (str)
Return type:: None

exception kdbxtool.exceptions.AuthenticationError(message='Authentication failed - wrong credentials or corrupted data')[source]¶

Bases: CryptoError

HMAC or integrity verification failed.

The database’s authentication code doesn’t match, indicating either wrong credentials or data tampering.

Parameters:: message (str)
Return type:: None

__init__(message='Authentication failed - wrong credentials or corrupted data')[source]¶

Parameters:: message (str)
Return type:: None

exception kdbxtool.exceptions.KdfError[source]¶

Bases: CryptoError

Error in key derivation function.

Problems with KDF parameters, unsupported KDF types, or KDF computation failures.

exception kdbxtool.exceptions.UnknownCipherError(cipher_uuid)[source]¶

Bases: CryptoError

Unknown or unsupported cipher algorithm.

The database uses a cipher that this library doesn’t recognize.

Parameters:: cipher_uuid (bytes)
Return type:: None

__init__(cipher_uuid)[source]¶

Parameters:: cipher_uuid (bytes)
Return type:: None

exception kdbxtool.exceptions.TwofishNotAvailableError[source]¶

Bases: CryptoError

Twofish cipher requested but oxifish package not installed.

The database uses Twofish encryption, which requires the optional oxifish package. Install it with: pip install kdbxtool[twofish]

Return type:: None

__init__()[source]¶

Return type:: None

exception kdbxtool.exceptions.CredentialError[source]¶

Bases: KdbxError

Error with database credentials.

Base class for credential-related errors. Messages are kept generic to avoid information disclosure about which credential component is incorrect.

exception kdbxtool.exceptions.InvalidPasswordError(message='Invalid password')[source]¶

Bases: CredentialError

Invalid or missing password.

Note: This is only raised when we can definitively determine the password is wrong without revealing information about other credential components.

Parameters:: message (str)
Return type:: None

__init__(message='Invalid password')[source]¶

Parameters:: message (str)
Return type:: None

exception kdbxtool.exceptions.InvalidKeyFileError(message='Invalid keyfile')[source]¶

Bases: CredentialError

Invalid or missing keyfile.

The keyfile is malformed, has wrong format, or failed hash verification.

Parameters:: message (str)
Return type:: None

__init__(message='Invalid keyfile')[source]¶

Parameters:: message (str)
Return type:: None

exception kdbxtool.exceptions.MissingCredentialsError[source]¶

Bases: CredentialError

No credentials provided.

At least one credential (password or keyfile) is required to open or create a database.

Return type:: None

__init__()[source]¶

Return type:: None

exception kdbxtool.exceptions.YubiKeyError[source]¶

Bases: CredentialError

Error communicating with YubiKey.

Base class for YubiKey-related errors. These occur during challenge-response authentication with a hardware YubiKey.

exception kdbxtool.exceptions.YubiKeyNotFoundError(message=None)[source]¶

Bases: YubiKeyError

No YubiKey detected.

No YubiKey device was found connected to the system. Ensure the YubiKey is properly inserted.

Parameters:: message (str | None)
Return type:: None

__init__(message=None)[source]¶

Parameters:: message (str | None)
Return type:: None

exception kdbxtool.exceptions.YubiKeySlotError(slot)[source]¶

Bases: YubiKeyError

YubiKey slot not configured for HMAC-SHA1.

The specified slot on the YubiKey is not configured for HMAC-SHA1 challenge-response authentication.

Parameters:: slot (int)
Return type:: None

__init__(slot)[source]¶

Parameters:: slot (int)
Return type:: None

exception kdbxtool.exceptions.YubiKeyTimeoutError(timeout_seconds=15.0)[source]¶

Bases: YubiKeyError

YubiKey operation timed out.

The YubiKey operation timed out, typically because touch was required but not received within the timeout period.

Parameters:: timeout_seconds (float)
Return type:: None

__init__(timeout_seconds=15.0)[source]¶

Parameters:: timeout_seconds (float)
Return type:: None

exception kdbxtool.exceptions.YubiKeyNotAvailableError[source]¶

Bases: YubiKeyError

YubiKey support requested but yubikey-manager not installed.

The yubikey-manager package is required for YubiKey challenge-response authentication. Install it with: pip install kdbxtool[yubikey]

Return type:: None

__init__()[source]¶

Return type:: None

exception kdbxtool.exceptions.DatabaseError[source]¶

Bases: KdbxError

Error in database operations.

Base class for errors that occur during database manipulation after successful decryption.

exception kdbxtool.exceptions.EntryNotFoundError(message='Entry not found')[source]¶

Bases: DatabaseError

Entry not found in database.

The requested entry doesn’t exist or was not found in the specified location.

Parameters:: message (str)
Return type:: None

__init__(message='Entry not found')[source]¶

Parameters:: message (str)
Return type:: None

exception kdbxtool.exceptions.GroupNotFoundError(message='Group not found')[source]¶

Bases: DatabaseError

Group not found in database.

The requested group doesn’t exist or was not found in the database hierarchy.

Parameters:: message (str)
Return type:: None

__init__(message='Group not found')[source]¶

Parameters:: message (str)
Return type:: None

exception kdbxtool.exceptions.InvalidXmlError(message='Invalid KDBX XML structure')[source]¶

Bases: DatabaseError

Invalid or malformed XML payload.

The decrypted XML content doesn’t conform to the expected KDBX XML schema.

Parameters:: message (str)
Return type:: None

__init__(message='Invalid KDBX XML structure')[source]¶

Parameters:: message (str)
Return type:: None

exception kdbxtool.exceptions.Kdbx3UpgradeRequired[source]¶

Bases: DatabaseError

KDBX3 database requires explicit upgrade confirmation.

When saving a KDBX3 database to its original file, explicit confirmation is required since the save will upgrade it to KDBX4. Use save(allow_upgrade=True) to confirm the upgrade.

Return type:: None

__init__()[source]¶

Return type:: None

exception kdbxtool.exceptions.MergeError(message='Merge operation failed')[source]¶

Bases: DatabaseError

Error during database merge operation.

Raised when a merge operation fails due to incompatible databases, invalid state, or other merge-specific issues.

Parameters:: message (str)
Return type:: None

__init__(message='Merge operation failed')[source]¶

Parameters:: message (str)
Return type:: None