Skip to main content

Error

Enum Error 

Source
#[non_exhaustive]
pub enum Error {
Show 24 variants InvalidToken(String), Config(String), Transport { address: String, source: Error, }, Grpc(Box<Status>), InvalidEngineVersion(String), UnsupportedEngine { found: String, minimum: String, }, UnsupportedFeature { feature: String, found: String, minimum: String, }, InvalidDeclaration(String), ParentOutput { task: String, reason: String, }, Detached(String), InvalidArgument(String), Json(String), RunFailed { run_id: String, errors: Vec<TaskFailure>, }, RunCancelled { run_id: String, tasks: Vec<String>, }, RunOutput { run_id: String, reason: String, }, UnknownRunStatus { run_id: String, status: i32, }, StreamGap { task_run_id: String, expected: i64, got: i64, }, ResultStream(Box<Status>), PartialBulkTrigger { run_ids: Vec<String>, source: Box<Error>, }, BulkTriggerMismatch { expected: usize, got: usize, }, IdempotencyCollision(IdempotencyCollision), BulkIdempotencyCollision { started: Vec<String>, collisions: Vec<IdempotencyCollision>, }, Nondeterminism { task_run_id: String, invocation_count: i32, node_id: i64, message: String, }, DurableEntryFailed { task_run_id: String, invocation_count: i32, node_id: i64, message: String, },
}
Expand description

Errors returned by hatchet-client.

Variants (Non-exhaustive)§

This enum is marked as 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.
§

InvalidToken(String)

The API token is not a JWT carrying the claims the SDK needs. The message never contains the token itself.

§

Config(String)

The configuration is incomplete or contradictory.

§

Transport

The gRPC channel could not be set up.

Fields

§address: String

The host:port being connected to.

§source: Error

The underlying transport error.

§

Grpc(Box<Status>)

The engine answered a gRPC call with an error status.

§

InvalidEngineVersion(String)

The engine reported a version string that is not vMAJOR.MINOR.PATCH.

§

UnsupportedEngine

The engine is older than the SDK supports.

Fields

§found: String

The version the engine reported.

§minimum: String

The oldest version this SDK works with.

§

UnsupportedFeature

The engine is new enough for this SDK, but not for one thing a declaration asked for. Reported when the worker registers, rather than letting the engine quietly ignore the field.

Fields

§feature: String

What was asked for, e.g. "idempotency".

§found: String

The version the engine reported.

§minimum: String

The oldest version that supports it.

§

InvalidDeclaration(String)

A task or workflow declaration is invalid (duplicate task names, an unknown parent, …). Reported when the declaration is registered.

§

ParentOutput

A parent task’s output was asked for but is not available: either the named task is not actually a recorded parent, or its output does not deserialize into the type asked for.

Fields

§task: String

The parent task name that was asked for.

§reason: String

Why the lookup failed.

§

Detached(String)

The call needs a Context attached to a client (e.g. a refresh_timeout or spawn call), but this one is not — it was built for tests, without a worker behind it.

§

InvalidArgument(String)

An argument given to the SDK is not valid (a zero-duration timeout increment, a priority out of range, …).

§

Json(String)

A value the SDK was asked to send could not be serialized to JSON: a run’s input, or a metadata map.

§

RunFailed

A run that was waited for finished with at least one failed task.

A run that was cancelled is Error::RunCancelled instead, except when something in it really failed as well: a run with one of each is reported here, because the failure is the part that needs fixing.

Fields

§run_id: String

The run that failed.

§errors: Vec<TaskFailure>

Every task of that run that reported an error.

§

RunCancelled

A run that was waited for was cancelled before it finished: by RunsClient::cancel, by RunHandle::cancel, by a Concurrency limit that cancels rather than queues, or from the dashboard.

Told apart from Error::RunFailed by what the engine records for a cancelled task: an error it never filled in (the empty string) and no output at all. That is the only signal there is — the result stream has one event type (FINISHED) and its rows carry no status field — and it was measured on both supported engine versions, for an explicit CancelTasks and for a concurrency limit. A run whose tasks both failed and were cancelled is reported as Error::RunFailed instead.

use hatchet_client::Error;

fn report(result: Result<u32, Error>) {
    match result {
        Ok(count) => println!("counted {count}"),
        // Not a failure: someone stopped it on purpose. Retrying
        // would undo their decision.
        Err(Error::RunCancelled { run_id, .. }) => println!("{run_id} was stopped"),
        Err(other) => println!("failed: {other}"),
    }
}

Fields

§run_id: String

The run that was cancelled.

§tasks: Vec<String>

The tasks of that run the engine recorded as cancelled, as declared. Empty when the engine named none.

§

RunOutput

A finished run’s output is not there, or does not deserialize into the type it was asked for. Deserializing is reading rather than sending, which is why this is not Error::Json.

Fields

§run_id: String

The run whose output was asked for.

§reason: String

Why the output could not be handed back.

§

UnknownRunStatus

The engine reported a run status this SDK has no name for. Only an engine newer than this SDK can produce it: the statuses of api-contracts/v1/workflows.proto are all covered. Reported rather than rounded to a status we do know, which is what the official Go SDK does (pkg/client/admin.go:136-137, unknown → QUEUED).

Fields

§run_id: String

The run being asked about.

§status: i32

The value on the wire.

§

StreamGap

A run’s output stream skipped a chunk: the engine sent an event_index further along than the one expected next, and the chunks in between did not turn up.

Yielded as one item of the stream — one item per missing stretch, in the place that stretch would have taken — and the stream carries on from where the engine is. Losing part of the output is not a reason to stop delivering the rest, but it is not something to hide either: a consumer that must have everything should treat this as fatal itself.

Chunks are numbered per task run, by Context::put_stream, so task_run_id names the sequence with the gap in it.

use hatchet_client::Error;

fn report(item: Result<hatchet_client::StreamChunk, Error>) {
    match item {
        Ok(chunk) => println!("{}", chunk.payload),
        // The stream goes on; this is one hole in it, not the end.
        Err(Error::StreamGap { expected, got, .. }) => {
            println!("missed chunks {expected}..{got}");
        }
        Err(other) => println!("the stream failed: {other}"),
    }
}

Fields

§task_run_id: String

The task run whose chunk sequence has the gap.

§expected: i64

The index that was expected next.

§got: i64

The index that arrived instead.

§

ResultStream(Box<Status>)

The stream a run’s result would have arrived on was given up on: the engine ended it in a way reconnecting cannot fix, or kept ending it. The run itself is unaffected — it is still running, and waiting for it again opens a new subscription.

§

PartialBulkTrigger

A Task::run_many or Workflow::run_many call started some runs before failing: the ids in run_ids were really triggered and are not lost, even though the call as a whole failed. They come from the chunks that succeeded and, when the failure is a Error::BulkTriggerMismatch, from the too-short answer itself — every id the engine returned names a run it started. Only returned once at least one run id was obtained; when nothing was started, source is returned on its own instead.

Fields

§run_ids: Vec<String>

The ids of the runs that were started, in input order.

§source: Box<Error>

Why the failing chunk failed.

§

BulkTriggerMismatch

The engine answered a BulkTriggerWorkflow call with a different number of run ids than the chunk sent had requests. Treated as that chunk’s failure.

Fields

§expected: usize

How many requests the chunk sent.

§got: usize

How many ids the engine answered with.

§

IdempotencyCollision(IdempotencyCollision)

A trigger was refused because its idempotency key is already held by another run. The workflow declared the key with Workflow::idempotency or TaskBuilder::idempotency; no run was started by the call that got this. Only enforced on engines at or above IDEMPOTENCY_MIN_ENGINE_VERSION; older engines silently ignore the key instead of returning this.

use hatchet_client::Error;

fn handle(result: Result<String, Error>) {
    match result {
        Ok(run_id) => println!("started {run_id}"),
        Err(Error::IdempotencyCollision(collision)) => {
            println!("already running as {}", collision.existing_run_id);
        }
        Err(other) => println!("failed: {other}"),
    }
}
§

BulkIdempotencyCollision

A Task::run_many or Workflow::run_many call in which some requests were refused on their idempotency key. The ones in started really were triggered.

Fields

§started: Vec<String>

The runs the same call did start, in the engine’s order.

§collisions: Vec<IdempotencyCollision>

One entry per refused request.

§

Nondeterminism

The engine rejected a durable request because this attempt did not repeat what the last one did.

A durable handler is re-executed from the top on every attempt, and the engine matches each durable operation against its event log by position. Reaching a different operation — or reaching them in a different order — is this error, and retrying cannot help: the run is reported failed with should_not_retry. Common causes: racing durable waits against tokio::time::timeout or select!, branching on something that is not memoised (the clock, a random number, a live API call), or changing the handler’s durable steps while runs are in flight.

Fields

§task_run_id: String

The durable task run: Context::task_run_id.

§invocation_count: i32

Which attempt this was.

§node_id: i64

The log entry the engine was expecting something else at.

§message: String

What the engine said. The wording differs between engine versions, so match on this variant rather than on the text.

§

DurableEntryFailed

A durable log entry the engine completed as a failure.

The engine says a durable wait is over and that what it was waiting for went wrong; turning that into a success would hide it, so the handler sees the failure instead. Retrying is allowed: the attempt is reported as an ordinary task failure.

Fields

§task_run_id: String

The durable task run: Context::task_run_id.

§invocation_count: i32

Which attempt this was.

§node_id: i64

The log entry that failed.

§message: String

What the engine said, or a stand-in when it said nothing.

Trait Implementations§

Source§

impl Debug for Error

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Display for Error

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Error for Error

Source§

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

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

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

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

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. Read more
Source§

impl From<Status> for Error

Source§

fn from(status: Status) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

§

impl !RefUnwindSafe for Error

§

impl !UnwindSafe for Error

§

impl Forget for Error

§

impl Freeze for Error

§

impl Move for Error

§

impl Send for Error

§

impl Sync for Error

§

impl Unpin for Error

§

impl UnsafeUnpin for Error

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> FutureExt for T

Source§

fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
Source§

fn with_current_context(self) -> WithContext<Self> ⓘ

Attaches the current Context to this type, returning a WithContext wrapper. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoRequest<T> for T

Source§

fn into_request(self) -> Request<T>

Wrap the input message T in a tonic::Request
Source§

impl<L> LayerExt<L> for L

Source§

fn named_layer<S>(&self, service: S) -> Layered<<L as Layer<S>>::Service, S>
where L: Layer<S>,

Applies the layer to a service and wraps it in Layered.
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more