Skip to content

Error reference

Every way an atune call can fail, with the message it produces.

There is one error type. atune_core::Error is re-exported as atune::Error, atune::Result<T> is Result<T, Error>, and every fallible operation returns one — the library never panics to report a failure. Two variants are not failures at all: TrialPruned and TrialPaused are the ?-able sentinels a scheduler uses to stop an objective early, and a trial that ends with one is recorded as pruned or paused rather than failed.

The atune binary turns any of these into a message on standard error and a non-zero exit status; the values in Message below are what you see there.

This page is generated from crates/atune_core/src/error.rs — the variants, their #[error(…)] messages and their doc comments. A message is a compile-time template, so the generator reads the enum's source rather than the running code: that is the only way to publish unknown parameter {0} instead of one example of it. Types and method signatures are deliberately absent, because that is what the Rust API reference is for.

Generated file. Do not edit between the pragmas below — run cargo dev generate-all --mode write instead. Everything outside them is hand-written and is never touched.

atune_core::Error — re-exported as atune::Error — has 18 variants, declared in crates/atune_core/src/error.rs. The enum is #[non_exhaustive]: matching on it needs a wildcard arm, and a new variant is not a breaking change.

Error::TrialPruned

Message: trial pruned

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).

Error::TrialPaused

Message: trial paused

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.

Error::Incompatible

Message: parameter `{param}` is incompatible with the recorded distribution: {reason}

A parameter's distribution is incompatible with the one already recorded for that name in this study.

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.

Fields

  • param — The parameter name.
  • reason — Why the two distributions cannot describe the same parameter.

Error::UnknownParam

Message: unknown parameter `{0}`

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

Error::OutOfRange

Message: value for parameter `{param}` is out of range: {detail}

A value falls outside the support of its distribution.

Fields

  • param — The parameter name.
  • detail — What was expected and what was seen.

Error::InvalidSpace

Message: invalid search space: {0}

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.

Error::SpaceExhausted

Message: search space exhausted

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.

Error::LostRace

Message: lost a race against a concurrent worker

A concurrent worker won a race for the same resource.

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

Error::Backpressure

Message: backpressure: {0}

A bounded internal buffer is full, so the operation was refused.

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. Retrying after outstanding work drains is the intended response.

Error::ResourceLimit

Message: resource limit for {resource}: {limit}

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 — The bounded resource that rejected the operation.
  • limit — The configured finite limit.

Error::Unsupported

Message: unsupported: {0}

The selected backend does not provide the requested atomic capability.

Error::LeaseLost

Message: trial lease lost

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

Error::Conflict

Message: conflict: {0}

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.

Error::NotFound

Message: not found: {0}

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

Error::Storage

Message: storage: {0}

A storage backend failed for a backend-specific reason.

Error::Sampler

Message: sampler: {0}

A sampler failed to produce a value.

Error::Scheduler

Message: scheduler: {0}

A scheduler failed to reach a decision.

Error::Objective

Message: objective failed: {0}

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.

Keeps the underlying error as its source, so the whole cause chain survives.