Skip to content

Exceptions

exceptions

Exception hierarchy for adk-secure-sessions.

All library exceptions inherit from SecureSessionError to enable broad exception handling while keeping specific failure modes distinguishable in control flow.

Examples:

Catch all library errors:

from adk_secure_sessions.exceptions import SecureSessionError

try:
    await backend.decrypt(ciphertext)
except SecureSessionError:
    ...

Catch only decryption failures:

from adk_secure_sessions.exceptions import DecryptionError

try:
    await backend.decrypt(ciphertext)
except DecryptionError:
    ...
See Also

adk_secure_sessions.protocols: Encryption backend protocol definition.

SecureSessionError

Bases: Exception


              flowchart TD
              adk_secure_sessions.exceptions.SecureSessionError[SecureSessionError]

              

              click adk_secure_sessions.exceptions.SecureSessionError href "" "adk_secure_sessions.exceptions.SecureSessionError"

Base exception for all adk-secure-sessions errors.

All library-specific exceptions inherit from this class so callers can use a single except SecureSessionError clause to handle any failure originating from this package.

Examples:

Catch any library error regardless of type:

try:
    await backend.encrypt(plaintext)
except SecureSessionError:
    log.error("adk-secure-sessions operation failed")
Source code in src/adk_secure_sessions/exceptions.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class SecureSessionError(Exception):
    """Base exception for all adk-secure-sessions errors.

    All library-specific exceptions inherit from this class so callers
    can use a single ``except SecureSessionError`` clause to handle any
    failure originating from this package.

    Examples:
        Catch any library error regardless of type:

        ```python
        try:
            await backend.encrypt(plaintext)
        except SecureSessionError:
            log.error("adk-secure-sessions operation failed")
        ```
    """

EncryptionError

Bases: SecureSessionError, DontWrapMixin


              flowchart TD
              adk_secure_sessions.exceptions.EncryptionError[EncryptionError]
              adk_secure_sessions.exceptions.SecureSessionError[SecureSessionError]

                              adk_secure_sessions.exceptions.SecureSessionError --> adk_secure_sessions.exceptions.EncryptionError
                


              click adk_secure_sessions.exceptions.EncryptionError href "" "adk_secure_sessions.exceptions.EncryptionError"
              click adk_secure_sessions.exceptions.SecureSessionError href "" "adk_secure_sessions.exceptions.SecureSessionError"

Raised when encryption fails.

Inherits DontWrapMixin so SQLAlchemy propagates this directly instead of wrapping it in StatementError.

Possible causes include invalid plaintext input or backend-specific errors. Error messages intentionally exclude key material, plaintext, and ciphertext to prevent information leakage.

Examples:

Handle encryption failures specifically:

try:
    ciphertext = await backend.encrypt(plaintext)
except EncryptionError:
    log.error("Encryption failed")
Source code in src/adk_secure_sessions/exceptions.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
class EncryptionError(SecureSessionError, DontWrapMixin):
    """Raised when encryption fails.

    Inherits ``DontWrapMixin`` so SQLAlchemy propagates this directly
    instead of wrapping it in ``StatementError``.

    Possible causes include invalid plaintext input or backend-specific
    errors. Error messages intentionally exclude key material, plaintext,
    and ciphertext to prevent information leakage.

    Examples:
        Handle encryption failures specifically:

        ```python
        try:
            ciphertext = await backend.encrypt(plaintext)
        except EncryptionError:
            log.error("Encryption failed")
        ```
    """

DecryptionError

Bases: SecureSessionError, DontWrapMixin


              flowchart TD
              adk_secure_sessions.exceptions.DecryptionError[DecryptionError]
              adk_secure_sessions.exceptions.SecureSessionError[SecureSessionError]

                              adk_secure_sessions.exceptions.SecureSessionError --> adk_secure_sessions.exceptions.DecryptionError
                


              click adk_secure_sessions.exceptions.DecryptionError href "" "adk_secure_sessions.exceptions.DecryptionError"
              click adk_secure_sessions.exceptions.SecureSessionError href "" "adk_secure_sessions.exceptions.SecureSessionError"

Raised when decryption fails.

Inherits DontWrapMixin so SQLAlchemy propagates this directly instead of wrapping it in StatementError.

Possible causes include a wrong key, tampered ciphertext, or malformed input. Error messages intentionally exclude key material, ciphertext, and plaintext to prevent information leakage.

Examples:

Handle decryption failures specifically:

try:
    plaintext = await backend.decrypt(ciphertext)
except DecryptionError:
    log.error("Decryption failed, check key")
Source code in src/adk_secure_sessions/exceptions.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
class DecryptionError(SecureSessionError, DontWrapMixin):
    """Raised when decryption fails.

    Inherits ``DontWrapMixin`` so SQLAlchemy propagates this directly
    instead of wrapping it in ``StatementError``.

    Possible causes include a wrong key, tampered ciphertext, or
    malformed input. Error messages intentionally exclude key material,
    ciphertext, and plaintext to prevent information leakage.

    Examples:
        Handle decryption failures specifically:

        ```python
        try:
            plaintext = await backend.decrypt(ciphertext)
        except DecryptionError:
            log.error("Decryption failed, check key")
        ```
    """

SerializationError

Bases: SecureSessionError, DontWrapMixin


              flowchart TD
              adk_secure_sessions.exceptions.SerializationError[SerializationError]
              adk_secure_sessions.exceptions.SecureSessionError[SecureSessionError]

                              adk_secure_sessions.exceptions.SecureSessionError --> adk_secure_sessions.exceptions.SerializationError
                


              click adk_secure_sessions.exceptions.SerializationError href "" "adk_secure_sessions.exceptions.SerializationError"
              click adk_secure_sessions.exceptions.SecureSessionError href "" "adk_secure_sessions.exceptions.SecureSessionError"

Raised when data cannot be serialized to JSON.

Inherits DontWrapMixin so SQLAlchemy propagates this directly instead of wrapping it in StatementError.

This indicates a caller bug — the input contains types that are not JSON-serializable (e.g., datetime, custom objects). This is distinct from encryption/decryption failures which indicate configuration or data integrity issues.

Examples:

Handle serialization failures:

try:
    envelope = await encrypt_session(data, backend, backend_id)
except SerializationError:
    log.error("Data contains non-JSON-serializable values")
Source code in src/adk_secure_sessions/exceptions.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
class SerializationError(SecureSessionError, DontWrapMixin):
    """Raised when data cannot be serialized to JSON.

    Inherits ``DontWrapMixin`` so SQLAlchemy propagates this directly
    instead of wrapping it in ``StatementError``.

    This indicates a caller bug — the input contains types that are not
    JSON-serializable (e.g., ``datetime``, custom objects). This is
    distinct from encryption/decryption failures which indicate
    configuration or data integrity issues.

    Examples:
        Handle serialization failures:

        ```python
        try:
            envelope = await encrypt_session(data, backend, backend_id)
        except SerializationError:
            log.error("Data contains non-JSON-serializable values")
        ```
    """

ConfigurationError

Bases: SecureSessionError


              flowchart TD
              adk_secure_sessions.exceptions.ConfigurationError[ConfigurationError]
              adk_secure_sessions.exceptions.SecureSessionError[SecureSessionError]

                              adk_secure_sessions.exceptions.SecureSessionError --> adk_secure_sessions.exceptions.ConfigurationError
                


              click adk_secure_sessions.exceptions.ConfigurationError href "" "adk_secure_sessions.exceptions.ConfigurationError"
              click adk_secure_sessions.exceptions.SecureSessionError href "" "adk_secure_sessions.exceptions.SecureSessionError"

Raised when the service is misconfigured at startup.

Covers invalid encryption keys, backends that do not conform to the EncryptionBackend protocol, invalid backend IDs, empty database paths, and database connection failures. Error messages never include key material or other sensitive data.

Examples:

Handle configuration failures at startup:

try:
    service = EncryptedSessionService(
        db_url="sqlite+aiosqlite:///sessions.db",
        backend=my_backend,
    )
except ConfigurationError as exc:
    log.error("Service misconfigured: %s", exc)
Source code in src/adk_secure_sessions/exceptions.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class ConfigurationError(SecureSessionError):
    """Raised when the service is misconfigured at startup.

    Covers invalid encryption keys, backends that do not conform to the
    ``EncryptionBackend`` protocol, invalid backend IDs, empty database
    paths, and database connection failures. Error messages never include
    key material or other sensitive data.

    Examples:
        Handle configuration failures at startup:

        ```python
        try:
            service = EncryptedSessionService(
                db_url="sqlite+aiosqlite:///sessions.db",
                backend=my_backend,
            )
        except ConfigurationError as exc:
            log.error("Service misconfigured: %s", exc)
        ```
    """