Errors¶
Typed exceptions raised by the Durable Workflow client and worker.
Every error exception inherits from DurableWorkflowError, so
callers that only want to distinguish SDK errors from unrelated failures can
catch that base. More specific subclasses let callers react to particular
outcomes — workflow-not-found, update-rejected, schedule-already-exists —
without parsing server response bodies.
Cancellation is intentionally not in that hierarchy. WorkflowCancelled
and ActivityCancelled inherit from BaseException directly,
so a generic except Exception: block cannot accidentally swallow a
cancellation signal. Callers that want to handle cancellation must name the
class explicitly (except (ActivityCancelled, ...):). This mirrors the way
asyncio.CancelledError and KeyboardInterrupt behave in the
standard library and avoids the historical mistake called out in
https://github.com/temporalio/sdk-python/issues/1292.
module-attribute
¶
Reason reported when a command key is reused with a different intent.
Bases: Exception
Base class for every exception raised by the SDK.
Bases: DurableWorkflowError, ValueError
Required failure identity or semantics cannot fit the reporting budget.
This is a local reporting refusal, not the application's failure. No claim identity, failure type or retry decision is shortened to make it fit.
Bases: DurableWorkflowError, ValueError
Workflow authoring uses an unsupported entry point or result.
Bases: DurableWorkflowError, ValueError
One registration scope assigns a wire name to multiple definitions.
Bases: DurableWorkflowError
Runtime discovery could not prove that an operation is available.
operation names the requested SDK operation and required_path is
the field the SDK expected from GET /api/cluster/info. cause is
retained when discovery itself failed.
Bases: DurableWorkflowError
Base class for failures at the runtime-owned payload boundary.
reason and retryable are stable protocol fields. status and
body preserve the runtime response when the failure came from HTTP;
local reference and integrity validation use the same typed hierarchy.
Bases: DurableWorkflowError
A server response was an error that does not map to a typed subclass.
The HTTP status is on status, and the parsed JSON body is on
body when the server returned one.
Return a delay only for an identity-preserving fenced transient.
Return the advertised wait only for a complete poll-capacity refusal.
Whether the runtime explicitly refused admission and requested an identity-preserving retry.
Bases: DurableWorkflowError
A workflow finished in the failed state.
exception_class carries the fully qualified name of the exception
class the workflow raised, when the server recorded one.
Bases: DurableWorkflowError
A start request collided with an existing instance id.
The PHP Server raises this for an existing workflow_id when the
duplicate policy is fail (the default), or when use-existing
addresses a closed instance. use-existing returns a handle only
while the original run is pending, running or waiting.
Bases: DurableWorkflowError
The server rejected the request as malformed (HTTP 422).
errors holds the structured validation errors from the response
body when the server returned them.
Bases: DurableWorkflowError
The request was rejected for missing or invalid authentication (HTTP 401).
Bases: ServerError
A schedule visibility filter or continuation cursor was refused.
The complete parsed response remains available on body. Convenience
attributes expose the rejected field, structured field errors, and the
server's last safe keyset cursor without discarding status or reason.
Return a delay only for an identity-preserving fenced transient.
Return the advertised wait only for a complete poll-capacity refusal.
Whether the runtime explicitly refused admission and requested an identity-preserving retry.
Bases: DurableWorkflowError
A workflow query was rejected or the workflow raised while handling it.
property
¶
Return structured query argument validation errors, if the server provided them.
Bases: DurableWorkflowError
A workflow signal was rejected before it could be delivered.
request_id is the caller command key the client sent with the
signal (caller-supplied or SDK-generated), so the application can retry
the same logical signal with the same key. reason is the Server's
machine-readable refusal reason; request_id_conflict means the key was
already retained for a signal with a different intent, and
details then carries retained_command_id,
retained_command_type, retained_outcome and the mismatched
conflict parts.
property
¶
Return structured signal argument validation errors, if the server provided them.
WorkflowPayloadDecodeError(message, *, workflow_id=None, run_id=None, event_id=None, receiver_kind=None, receiver_name=None, codec=None, payload_head=None, exception_type=None)
Bases: DurableWorkflowError
A committed workflow history payload could not be decoded during replay.
NonDeterministicReplayError(workflow_sequence, expected_shape, recorded_event_types, *, detail=None)
Bases: DurableWorkflowError
Current workflow code yielded a command shape that does not match history.
Bases: InvalidArgument
An accepted workflow update failed, or its command key was refused.
body preserves the Server response, including its durable failure
identity. This inherits from InvalidArgument to preserve catches
written for earlier SDK versions that mapped all HTTP 422 responses there.
request_id is the caller command key the client sent with the
update (caller-supplied or SDK-generated). reason is the Server's
machine-readable reason when it returned one; request_id_conflict
means the key was already retained for an update with a different intent,
and details then carries retained_command_id,
retained_command_type, retained_outcome and the mismatched
conflict parts.
ChildWorkflowFailed(message, exception_class=None, *, failure_kind=None, child_workflow_run_id=None, child_workflow_type=None)
Bases: DurableWorkflowError
A child workflow finished in the failed state.
Raised inside the parent workflow when it awaits the child's result.
exception_class mirrors the child's recorded exception class.
ChildWorkflowCancelled(message='child workflow was cancelled', exception_class=None, *, child_workflow_run_id=None, child_workflow_type=None)
Bases: ChildWorkflowFailed
A child workflow finished in the cancelled state.
Raised inside the parent workflow when it awaits a child that was
cancelled directly or by parent-close policy. It is a child outcome, so it
remains catchable as ChildWorkflowFailed.
ActivityFailed(message, *, activity_type=None, step_sequence=None, activity_execution_id=None, activity_attempt_id=None, failure_id=None, failure_category=None, exception_type=None, exception_class=None, non_retryable=False, code=None, exception_payload=None, activity=None)
Bases: DurableWorkflowError
An activity finished in the failed state.
Raised inside workflow code when it awaits an activity that exhausted its retry policy or reported a non-retryable failure. The attributes mirror the stable failure fields recorded in workflow history so saga workflows can branch or compensate without parsing raw history events.
Bases: DurableWorkflowError
A workflow was terminated by operator action.
Like terminal cancellation, termination does not resume workflow cleanup. It records a distinct terminal outcome.
Bases: DurableWorkflowError
A persisted workflow execution or run deadline expired.
Unlike a caller's TimeoutError while polling, this is a terminal
workflow outcome recorded by the runtime.
SagaCompensationFailed(initiating_failure, compensation_failure, *, compensation_activity_type, compensation_registration_order)
Bases: DurableWorkflowError
A saga compensation failed after an earlier workflow failure.
Both failures remain available as typed attributes so applications and failure serializers do not have to recover the initiating cause from formatted text.
Bases: BaseException
A workflow was cancelled and finished in the cancelled state.
Inherits from BaseException — not Exception — so that a
generic except Exception: block cannot accidentally swallow the
cancellation outcome. Callers that want to treat a cancelled workflow
differently from a failed one (e.g. to skip alerting) must catch this
class by name.
Bases: BaseException
An in-flight activity was cancelled.
Raised inside durable_workflow.ActivityContext.heartbeat when the
server reports that the task was revoked or its run was cancelled, so the
activity can exit on its next heartbeat. This permits local activity cleanup,
not durable workflow compensation after the run closes.
Inherits from BaseException — not Exception — so that a
user except Exception: block inside the activity function cannot
accidentally swallow the cancellation signal. Activities that need to run
cleanup on cancellation should catch this class by name and re-raise:
.. code-block:: python
try:
await activity.context().heartbeat()
except ActivityCancelled:
cleanup()
raise
Bases: DurableWorkflowError
Marker an activity can raise to fail its workflow without further retries.
The server stops retrying the activity and surfaces the failure to the workflow as a terminal activity error, regardless of the configured retry policy.
Bases: NonRetryableError, TypeError
A payload value does not match the receiver's declared type.
Raised by opt-in typed values: a typed=True activity's arguments, or an
activity result decoded to result_type. path names the field (for
example order.items[2].sku) and expected the declared type. The
message never contains the received value. An activity whose arguments do
not match fails without retries, because a retry cannot change the payload.
Bases: DurableWorkflowError, ImportError
Raised when the core avro runtime dependency is unavailable.