FHElium

Appearance

fhelium.errors ​

Typed public exceptions raised by FHElium.

The exception hierarchy is intentionally small and centralized. Callers may catch FHEliumError for package-level failures or a narrower category such as ConfigurationError or StateError.

ArtifactError ​

class View source

python
ArtifactError()

Bases: FHEliumError, RuntimeError

Base class for structured artifact identity and version failures.

ConfigurationError ​

class View source

python
ConfigurationError()

Bases: FHEliumError, ValueError

Invalid or unavailable cryptographic configuration.

CudaGraphCaptureError ​

class View source

python
CudaGraphCaptureError(*, stage: str, function_name: str, detail: str)

Bases: ExecutionError

A program failed during CUDA Graph warmup, capture, or first replay.

CudaGraphInputError ​

class View source

python
CudaGraphInputError()

Bases: ExecutionInputError

Replay input structure or exact-value state differs from capture.

ExecutionError ​

class View source

python
ExecutionError()

Bases: FHEliumError, RuntimeError

Base class for a failure in a FHElium execution program.

ExecutionInputError ​

class View source

python
ExecutionInputError()

Bases: ExecutionError

An input tree is incompatible with an execution buffer or program.

FHEliumError ​

class View source

python
FHEliumError()

Bases: Exception

Base class for FHElium-specific failures.

InsufficientPrimeCatalogError ​

class View source

python
InsufficientPrimeCatalogError(*, prime_kind: Literal['message', 'scale'], ring_dimension: int, required_count: int, available_count: int)

Bases: PrimeCatalogError

The catalog cannot supply the requested modulus-chain width.

InvalidScaleError ​

class View source

python
InvalidScaleError(*, value_name: str, scale: object)

Bases: ScaleError

A CKKS scale is not representable as a positive finite float.

MaximumLevelError ​

class View source

python
MaximumLevelError(*, level: int, maximum_level: int)

Bases: StateError

No further level drop is available for a ciphertext.

MessagePrimeCatalogEntryNotFoundError ​

class View source

python
MessagePrimeCatalogEntryNotFoundError(*, coefficient_bits: int, ring_dimension: int)

Bases: PrimeCatalogError

No message-prime catalog entry matches the requested parameters.

PolynomialDomainError ​

class View source

python
PolynomialDomainError(*, value_name: str, expected: Literal['coefficient', 'ntt'], actual: str | None)

Bases: StateError

A value is in the wrong polynomial domain for an operation.

PrimeCatalogError ​

class View source

python
PrimeCatalogError()

Bases: ConfigurationError

Base class for prime-catalog lookup, capacity, or resource failures.

PrimeCatalogResourceError ​

class View source

python
PrimeCatalogResourceError(*, resource_name: str, detail: str)

Bases: PrimeCatalogError

An installed immutable prime-catalog resource is missing or invalid.

ResidencyBudgetError ​

class View source

python
ResidencyBudgetError(*, location: str, budget_bytes: int, used_bytes: int, reserved_bytes: int, requested_bytes: int)

Bases: ResidencyError

A materialization or reservation exceeds one location budget.

ResidencyClosedError ​

class View source

python
ResidencyClosedError()

Bases: ResidencyError

A residency manager was used after it closed.

ResidencyError ​

class View source

python
ResidencyError()

Bases: FHEliumError, RuntimeError

Base class for managed value-residency failures.

ResidencyHandleError ​

class View source

python
ResidencyHandleError()

Bases: ResidencyError

A residency handle is unknown, foreign, discarded, or malformed.

ResidencyInUseError ​

class View source

python
ResidencyInUseError()

Bases: ResidencyError

An active read, hold, or pending CUDA event prevents a transition.

ResidencyLifetimeClosedError ​

class View source

python
ResidencyLifetimeClosedError()

Bases: ResidencyError

A released residency lease, hold, or reservation was reused.

ResidencyMaterializationError ​

class View source

python
ResidencyMaterializationError()

Bases: ResidencyError

A source or transition produced an invalid materialization.

ResidencyOwnershipError ​

class View source

python
ResidencyOwnershipError()

Bases: ResidencyError

A transition would violate replica or recoverability ownership.

ResidencyPlanError ​

class View source

python
ResidencyPlanError()

Bases: ResidencyError

A residency plan is invalid or infeasible for the current state.

ResidencyPlanExecutionError ​

class View source

python
ResidencyPlanExecutionError(*, plan_name: str, phase: Literal['execute', 'reclaim', 'reserve', 'enter', 'exit'], partial_report: ResidencyPlanReport, failed_action: ResidencyAction | None, failed_action_index: int | None, detail: str, failed_reservation: MemoryReservation | None=None, failed_reservation_index: int | None=None)

Bases: ResidencyError

A preflighted residency plan failed after execution began.

partial_report contains every transition that completed before the failure. Those transitions remain committed. failed_action and failed_action_index identify the requested action that failed during action execution. failed_reservation and failed_reservation_index identify a scoped reservation admission failure. The fields for the other operation kind are None. The original runtime exception is retained as __cause__ by the manager.

Attributes ​

NameTypeDefault/value
partial_reportResidencyPlanReport
failed_actionResidencyAction | None
failed_reservationMemoryReservation | None

ResidencyReentrancyError ​

class View source

python
ResidencyReentrancyError()

Bases: ResidencyError

External source or user code re-entered an active transition.

ResidencySearchLimitError ​

class View source

python
ResidencySearchLimitError(*, request_name: str, state_limit: int, explored_states: int, detail: str)

Bases: ResidencyPlanError

Automatic residency planning stopped at its deterministic state limit.

ResidencyStaleStateError ​

class View source

python
ResidencyStaleStateError(*, expected_version: int, actual_version: int)

Bases: ResidencyPlanError

A residency decision targets an obsolete manager state.

ResidencyUnavailableError ​

class View source

python
ResidencyUnavailableError()

Bases: ResidencyError

A required value materialization is absent from a location.

ResidueRepresentationError ​

class View source

python
ResidueRepresentationError(*, value_name: str, expected: Literal['standard', 'montgomery'], actual: str | None)

Bases: StateError

A value has the wrong RNS residue representation for an operation.

ScaleError ​

class View source

python
ScaleError()

Bases: StateError, ValueError

Base class for invalid or incompatible CKKS scale metadata.

ScaleMismatchError ​

class View source

python
ScaleMismatchError(*, operation: str, lhs_name: str, lhs_scale: float, rhs_name: str, rhs_scale: float)

Bases: ScaleError

Two values have different scales for an exact-scale operation.

ScalePrimeCatalogEntryNotFoundError ​

class View source

python
ScalePrimeCatalogEntryNotFoundError(*, scale_bits: int, ring_dimension: int)

Bases: PrimeCatalogError

No scale-prime catalog entry matches the requested parameters.

SecretKeyModulusBasisError ​

class View source

python
SecretKeyModulusBasisError(*, operation: str, expected: Literal['Q', 'QP'], actual: str)

Bases: StateError

A secret key does not contain the modulus basis an operation needs.

SecurityBudgetExceededError ​

class View source

python
SecurityBudgetExceededError(*, scale_bits: int, ring_dimension: int, num_scale_primes: int, maximum_modulus_bits: int, requested_modulus_bits: int)

Bases: ConfigurationError

The requested modulus chain exceeds the configured security budget.

StaleArtifactReferenceError ​

class View source

python
StaleArtifactReferenceError(*, name: str, expected_artifact_id: str, current_artifact_id: str | None, differences: dict[str, tuple[object, object]] | None=None)

Bases: ArtifactError, ValueError

An artifact reference no longer names the store's active generation.

StateError ​

class View source

python
StateError()

Bases: FHEliumError, RuntimeError

Base class for an invalid cryptographic value state.

UnsupportedArtifactStoreVersionError ​

class View source

python
UnsupportedArtifactStoreVersionError(*, found_version: int, supported_versions: tuple[int, ...], migration_available: bool=False)

Bases: ArtifactError

A local artifact catalog uses an unsupported on-disk version.

Towards full-stack encrypted execution infrastructures

Released under the MIT License. Copyright VisualDust and FHElium contributors