Error Handling

Understand the exception hierarchy, error codes, and recommended caller behavior.

Apart from ordinary OSError, ValueError, and FileExistsError boundaries, every public OCTX exception inherits from OctxError and provides a stable code. Most exceptions also carry an optional path.

Exception hierarchy

Exception	Default error code	When it occurs
`OctxError`	`OCTX_ERROR`	Base class for all OCTX operation exceptions.
`OctxOpenError`	`OCTX_OPEN_ERROR`	Base class for failures to open a Package.
`OctxFormatError`	`OCTX_FORMAT_ERROR`	Corrupt ZIP, manifest, JSON, encoding, or payload format; specific instances may use more specific error codes.
`OctxSecurityError`	`OCTX_SECURITY_ERROR`	Unsafe paths, links, encrypted entries, source replacement, or another security violation.
`OctxResourceLimitError`	`OCTX_RESOURCE_LIMIT`	Input exceeds `ArchiveLimits`.
`OctxIntegrityError`	`OCTX_INTEGRITY_ERROR`	An integrity operation fails.
`OctxValidationError`	`OCTX_VALIDATION_ERROR`	Creation or unpacking requires a valid Package, but full validation fails.
`ReleaseVersionError`	`OCTX_RELEASE_VERSION_REQUIRED`	An old version is reused after content changes, or the new version does not move forward.
`DerivationRequired`	`OCTX_DERIVATION_REQUIRED`	An external Package is modified without explicitly creating a derived Asset.
`OutputExistsError`	`OCTX_OUTPUT_EXISTS`	The output path already contains a different immutable Package.

Recommended handling

from octx import (
    OctxError,
    OutputExistsError,
    ReleaseVersionError,
    create_octx,
)

try:
    result = create_octx(...)
except OutputExistsError:
    # Do not overwrite a different immutable Package that already exists.
    raise
except ReleaseVersionError:
    # Increase the Release version, then retry.
    raise
except OctxError as error:
    log(error.code, error.path, str(error))
    raise

OctxValidationError.report contains the complete ValidationReport:

from octx import OctxValidationError, unpack_octx

try:
    unpack_octx("asset.octx", "./expanded")
except OctxValidationError as error:
    print(error.report.to_dict())

Validation is not exception flow

When processing untrusted input, prefer calling validate_octx() directly. Ordinary ZIP, format, digest, and structural errors are converted into a report with valid=False:

report = validate_octx("upload.octx")
if not report.valid:
    return {"accepted": False, "validation": report.to_dict()}

Only invalid arguments themselves, such as max_issues <= 0, continue to raise ValueError.