#[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
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
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
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
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.
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
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
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
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).
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
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
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
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
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
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.
Trait Implementations§
Source§impl Error for Error
impl Error for Error
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> FutureExt for T
impl<T> FutureExt for T
Source§fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
Source§fn with_current_context(self) -> WithContext<Self> ⓘ
fn with_current_context(self) -> WithContext<Self> ⓘ
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
Source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T in a tonic::Request