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 20 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: `{param}` is incompatible with the recorded data: {reason}
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— The parameter name, or the persisted state's name.reason— Why the two distributions cannot describe the same parameter, or why the persisted data cannot be adopted.
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}
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.
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::OutcomeUncertain¶
Message: outcome uncertain: {0}
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.
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::Lineage¶
Message: trial {trial}: {reason}
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— The per-study number of the trial whose provenance is incomplete.reason— What is missing.
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.