aeat.adapters.outbound.storage._errors module

Typed exception hierarchy for the storage provider abstraction.

Provider and remote-mirror failures raised by adapters.outbound.storage.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.ErrorCode through core.errors.registry so the CLI taxonomy stays explicit.

StorageCorruptionError is the deliberate exception: it derives from core.errors.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.StorageError, which covers at-rest persistence and has a different parent chain.

See also

adapters.outbound.storage.StorageProvider

Provider Protocol whose implementations raise this hierarchy.

adapters.outbound.storage.ProviderObjectMetadata

Boundary record paired with integrity and corruption checks.

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

Bases: AeatError

Base class for every outbound storage-provider failure.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStorageValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: OutboundStorageError, ValueError

Raised when storage operation parameters fail validation.

Inherits from ValueError to remain compatible with pydantic validators while staying catchable as OutboundStorageError.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStorageNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: OutboundStorageError

Raised when a requested object or namespace does not exist.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStorageConflictError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: OutboundStorageError

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

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStoragePermissionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: OutboundStorageError

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

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStoragePathTooLongError(message=None, *, context=None, suggestion=None, translated_message=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)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStorageQuotaError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: OutboundStorageError

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

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStorageNetworkError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: OutboundStorageError

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

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStorageIntegrityError(message=None, *, context=None, suggestion=None, translated_message=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)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception OutboundStorageUnavailableError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: OutboundStorageError

Raised when the backend is reachable but signals temporary unavailability.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception StorageCorruptionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: CoreError

Raised when a sidecar file contains structurally invalid field types.

As a core.errors.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:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]