Enum Error 

#[non_exhaustive]
pub enum Error {
    TrialPruned,
    TrialPaused,
    Incompatible {
        param: String,
        reason: String,
    },
    UnknownParam(String),
    OutOfRange {
        param: String,
        detail: String,
    },
    InvalidSpace(String),
    SpaceExhausted,
    LostRace,
    Backpressure(String),
    ResourceLimit {
        resource: String,
        limit: usize,
    },
    Unsupported(String),
    LeaseLost,
    OutcomeUncertain(String),
    Conflict(String),
    NotFound(String),
    Storage(String),
    Lineage {
        trial: u64,
        reason: String,
    },
    Sampler(String),
    Scheduler(String),
    Objective(Box<dyn Error + Send + Sync>),
}

Everything that can go wrong inside atune.

The type is fully owned (no borrowed lifetimes) and Send + Sync, so it can cross thread and process boundaries, be stored in a trial record, and be boxed into a foreign error chain.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TrialPruned

The trial was pruned by the scheduler; the objective should stop.

This is the ?-able sentinel described in the module documentation. It signals a decision, not an error: the trial’s last intermediate value becomes its objective value (see FrozenTrial::objective_value).

TrialPaused

The trial was paused by the scheduler; the objective should stop, but the trial is not finished and may be resumed later.

The ?-able sibling of TrialPruned, returned by TrialCtx::report / TrialCtx::should_stop when a scheduler answers Decision::Pause. A trial that ends its evaluation this way is recorded as TrialState::Paused — it keeps its checkpoint reference and can be woken again with Command::ResumeTrial — rather than as a failure or a terminal prune.

Incompatible

A parameter’s distribution is incompatible with the one already recorded for that name in this study, or persisted data cannot be adopted by the code reading it.

For distributions, numeric bound drift is accepted; a change of categorical choice set, of log scaling, or of distribution kind is rejected — see Distribution::is_compatible_with.

For persisted state, param names the state (for example sampler state) rather than a parameter. A restore or replacement refuses a blob of another kind or of a schema version the reader does not migrate — see StateBlob::ensure_schema — and leaves the stored data untouched.

Fields

param: String

The parameter name, or the persisted state’s name.

reason: String

Why the two distributions cannot describe the same parameter, or why the persisted data cannot be adopted.

UnknownParam(String)

A parameter name was referenced that the search space does not declare.

OutOfRange

A value falls outside the support of its distribution.

Fields

param: String

The parameter name.

detail: String

What was expected and what was seen.

InvalidSpace(String)

A search space (or a single distribution) is malformed.

Raised by the fallible Distribution constructors: low > high, a non-finite bound, a non-positive step, a logarithmic distribution whose lower bound is not strictly positive, a duplicate parameter name, an empty or duplicated categorical choice set.

SpaceExhausted

A finite search space has no unvisited configuration left.

Returned by exhaustive samplers (Grid) once every point of the cartesian product has been handed out.

LostRace

A concurrent worker won a race for the same resource.

Callers should re-read state and retry rather than fail the study.

Backpressure(String)

Capacity is occupied or another active owner must finish first.

This is deliberately not silence: the alternative — dropping the oldest entry to make room — loses the record that lets a finished trial be matched back to the work that produced it, and a search that has quietly stopped learning looks exactly like one that is working. Recovery also reports this when a read-back confirms that a different held finalization claim won an acquisition race. Retrying after the outstanding work drains or the active owner finishes is the intended response; recovery itself does not retry a failed acquisition.

ResourceLimit

A bounded resource cannot fit the requested operation.

This is distinct from Backpressure: the operation is too large for its configured bound even when no other caller is contending for capacity.

Fields

resource: String

The bounded resource that rejected the operation.

limit: usize

The configured finite limit.

Unsupported(String)

The selected backend does not provide the requested atomic capability.

LeaseLost

An ownership-fenced operation was attempted with a stale owner/epoch token or stale lease observation.

OutcomeUncertain(String)

A mutation was submitted, but whether it committed is unknown.

The call failed where the change may or may not have become durable: SQLite reported an error from an atomic import’s COMMIT, or a remote lifecycle mutation lost its response and the reconnect reached a restarted server, whose replay ledger is gone. Do not retry blindly with a fresh operation id, which can apply the change twice. Replay the same operation id where the backend still offers it, or observe the durable state first and resubmit only what is missing.

is_retryable is false for this variant.

Conflict(String)

The requested operation contradicts durable state.

The canonical case is mutating a finished trial: Complete, Pruned and Failed trials are immutable — see the states a trial moves through.

NotFound(String)

The requested study, trial or state blob does not exist.

Storage(String)

A storage backend failed for a backend-specific reason.

Lineage

A trial’s fork provenance is missing or inconsistent, so its lineage cannot be exported as a recipe (Study::recipe).

Raised when a trial on the path names a parent the study does not contain, or is a fork without its atune.lineage record. Nothing is inferred from reports in its place.

Fields

trial: u64

The per-study number of the trial whose provenance is incomplete.

reason: String

What is missing.

Sampler(String)

A sampler failed to produce a value.

Scheduler(String)

A scheduler failed to reach a decision.

Objective(Box<dyn Error + Send + Sync>)

The user’s objective function failed.

The original error is preserved as the source of the chain so that a failed trial’s record keeps the real cause.

Implementations

impl Error

pub fn objective<E>(source: E) -> Self

where E: Error + Send + Sync + 'static,

Wraps a user error from an objective function.

use atune_core::error::Error;

let io = std::io::Error::other("checkpoint missing");
let err = Error::objective(io);
assert!(matches!(err, Error::Objective(_)));

pub const fn is_pruned(&self) -> bool

Returns true for the Error::TrialPruned sentinel.

Study loops use this to route a pruned trial to TrialState::Pruned instead of TrialState::Failed.

pub const fn is_paused(&self) -> bool

Returns true for the Error::TrialPaused sentinel.

Study loops use this to route a paused trial to TrialState::Paused — a resumable, non-terminal state — instead of TrialState::Failed.

pub const fn is_retryable(&self) -> bool

Returns true if retrying the operation may succeed.

Lost races and stale lease observations can be transient. This is a retry hint, not a guarantee that replaying an arbitrary operation is safe. Error::OutcomeUncertain is never retryable: the failed mutation may already have committed. Study::optimize uses it when ask fails before the objective runs; failed-trial retries are a study-level concern.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.