cadrumo.adapters.outbound.storage.errors module

Typed exception hierarchy for the storage provider abstraction.

Provider and remote-mirror failures raised by adapters.outbound.storage.protocol.StorageProvider implementations use subclasses of OutboundStorageError so the application layer’s sync coordinator can dispatch on the concrete failure mode without parsing upstream error strings. Each public leaf binds to a stable core.errors.error_codes.ErrorCode through core.errors.registry so the CLI taxonomy stays explicit.

StorageCorruptionError is the deliberate exception: it derives from core.errors.hierarchy.CoreError because it represents structurally invalid sidecar metadata, not a remote-provider transport, quota, permission, or mirror failure.

The Outbound prefix disambiguates this hierarchy from the persistence side adapters.persistence.storage.errors.StorageError, which covers at-rest persistence and has a different parent chain.

See also

adapters.outbound.storage.protocol.StorageProvider

Provider Protocol whose implementations raise this hierarchy.

adapters.outbound.storage.records.ProviderObjectMetadata

Boundary record paired with integrity and corruption checks.

exception OutboundStorageError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: TerminalPreconditionErrorMixin[PreconditionVerdict], CadrumoError

Base class for every outbound storage-provider failure.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStorageValidationError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when storage operation parameters fail validation.

Pydantic-facing callers translate this registered error at their narrow validator boundary when required; provider code keeps the registered outbound-storage type.

Parameters:
Return type:

None

code
exception OutboundStorageNotFoundError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when a requested object or namespace does not exist.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStorageConflictError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when a put / move / rename collides with an existing object.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStoragePermissionError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when the active credentials lack the required scope or grant.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStoragePathTooLongError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when a resolved on-disk path exceeds the platform’s path-length ceiling.

Classified via core.paths.is_windows_long_path_error() from a caught WinError 3 / WinError 206 on legacy (non long-path-aware) Windows workstations. Distinct from OutboundStorageConflictError so the CLI surfaces the actual cause (a storage root too deep for the MAX_PATH ceiling) instead of a generic write-conflict message.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStorageQuotaError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when the backend rejects an operation due to quota exhaustion.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStorageNetworkError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when the backend endpoint is unreachable (DNS/TLS/timeout).

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStorageIntegrityError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when fetched provider data fails integrity checks.

The shared hash comparison path is adapters.outbound.storage._integrity.verify_content_hash().

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception OutboundStorageUnavailableError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: OutboundStorageError

Raised when the backend is reachable but signals temporary unavailability.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

  • precondition_verdict (VerdictT | None)

Return type:

None

code
exception StorageCorruptionError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: TerminalPreconditionErrorMixin[PreconditionVerdict], CoreError

Raised when a sidecar file contains structurally invalid field types.

As a core.errors.hierarchy.CoreError, this indicates on-disk data corruption: the sidecar JSON parses successfully but a required field (e.g. byte_length) carries a type that the runtime cannot coerce to the expected primitive. Unlike OutboundStorageIntegrityError, which covers payload-byte hash mismatches from adapters.outbound.storage._integrity.verify_content_hash(), this error surfaces schema-level violations in the sidecar metadata file itself.

Parameters:
Return type:

None

code