synology_apm_repo.sdk.errors module

Exception hierarchy for synology-apm-repo-sdk.

Every ApmRepoError carries two optional pieces of context:

  • ref: the node/file the error refers to, as a plain string (a store-relative path, a file_map path, str(node_ref), …).

  • spec: the FORMAT-SPEC.md subsection explaining why this is an error.

The hierarchy covers repository data, backend and worker failures, and InvalidArgumentError; other argument and programmer errors raise stdlib ValueError/IndexError. Names avoid shadowing builtins such as KeyError.

exception synology_apm_repo.sdk.errors.ApmRepoError(message, *, ref=None, spec=None)

Bases: Exception

Base of all errors raised by synology-apm-repo-sdk.

property safe_message: str

The message alone, without the [ref=...]/[spec=...] tags str(exc) appends — for a presentation layer’s non-verbose rendering. str(exc) keeps the full detail.

exception synology_apm_repo.sdk.errors.FormatError(message, *, ref=None, spec=None)

Bases: ApmRepoError

The bytes at ref do not match the on-disk format they were expected to have (magic mismatch, CRC mismatch, unsupported header version, truncated file, …).

exception synology_apm_repo.sdk.errors.DataCorruptError(message, *, ref=None, spec=None)

Bases: FormatError

An integrity check failed: a magic, CRC32 or other self-consistency check did not match, so the bytes did not survive intact.

classmethod from_missing(exc)

exc’s message, ref and spec as corruption: for a file the repository’s own records name (a listing, a probe that just found it), absent is damage, not a lookup miss. Raise it from exc.

exception synology_apm_repo.sdk.errors.UnsupportedVersionError(message, *, ref=None, spec=None)

Bases: FormatError

The on-disk format version is one this SDK does not read: a newer major version, or an obsolete layout.

exception synology_apm_repo.sdk.errors.ChunkCompactedError(message, *, ref=None, spec=None)

Bases: FormatError

SizeStore reports CompressType.COMPACTED for this chunk — the data was reclaimed by the write-side compactor and can no longer be read (FORMAT-SPEC.md: SizeStore).

exception synology_apm_repo.sdk.errors.KeyMaterialError(message, *, ref=None, spec=None)

Bases: ApmRepoError

The key string itself (<userKeyID>@<base64(userKey)>) is malformed, or does not match this repository’s wrapped VaultKey.

exception synology_apm_repo.sdk.errors.KeyRequiredError(message, *, ref=None, spec=None)

Bases: KeyMaterialError

The repository, or the data being read, is encrypted but no key was supplied.

exception synology_apm_repo.sdk.errors.KeyMismatchError(message, *, ref=None, spec=None)

Bases: KeyMaterialError

The supplied key does not unwrap this repository’s VaultKey, or was already rejected by Repository.set_key() (FORMAT-SPEC.md: Key hierarchy).

exception synology_apm_repo.sdk.errors.InvalidArgumentError(message, *, ref=None, spec=None)

Bases: ApmRepoError, ValueError

The caller’s ref or path cannot be acted on as given — malformed past parsing, too short, or matching several candidates — as opposed to naming something that does not exist. Also a ValueError.

exception synology_apm_repo.sdk.errors.NotFoundError(message, *, ref=None, spec=None)

Bases: ApmRepoError

The referenced path / node / version / object does not exist in this repository — as opposed to existing but being unreadable.

exception synology_apm_repo.sdk.errors.ContentUnavailableError(message, *, ref=None, spec=None)

Bases: ApmRepoError

This node’s metadata was found but its content can’t be read: the guest held only a placeholder at backup time (e.g. a cloud-only OneDrive/iCloud file), or the bytes need key material this SDK lacks (e.g. NTFS EFS). Says nothing about damage, and is deliberately not a NotFoundError, so code skipping absent nodes doesn’t swallow it.

exception synology_apm_repo.sdk.errors.NotRestorableError(message, *, ref=None, spec=None)

Bases: ApmRepoError

A resolved node/item that has no restorable content (a folder, a group, a node missing the metadata its content comes from).

exception synology_apm_repo.sdk.errors.PermissionDeniedError(message, *, ref=None, spec=None)

Bases: ApmRepoError

The OS or backend denied reading or listing an existing path; deliberately not a NotFoundError, so code skipping absent paths doesn’t swallow it.

exception synology_apm_repo.sdk.errors.StorageBackendError(message, *, ref=None, spec=None)

Bases: ApmRepoError

The storage backend failed to serve a request — a network or transport failure, a timeout, a service-side error, or an OS-level I/O error. Not a statement about the repository’s data, so code that turns unreadable data into a finding or a placeholder re-raises it instead.

exception synology_apm_repo.sdk.errors.UnsupportedDataFormatError(message, *, ref=None, spec=None)

Bases: ApmRepoError

The content exists but this version of the SDK deliberately refuses to interpret it (e.g. a CBT merge chain) rather than risk emitting silently-wrong bytes.

exception synology_apm_repo.sdk.errors.ResourceLimitExceededError(message, *, ref=None, spec=None)

Bases: ApmRepoError

A requested size exceeds a safety ceiling (a guard against a corrupt or hostile repository’s implausible sizes, e.g. one DedupFile.read()) or the free disk space a temporary copy needs with a reserve left over (storage.disk_space); not a claim that the bytes are damaged.

exception synology_apm_repo.sdk.errors.WorkerProcessError(message, *, ref=None, spec=None)

Bases: ApmRepoError

A worker process of an export or a FULL verify died (killed, out of memory, crashed), so the operation was aborted. Not a statement about the repository’s data.