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.
Bases: Exception
Base class for every exception raised by the SDK.
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.
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.
Raised when duplicate-start policy is reject (the default) and the
caller-supplied workflow_id is already in use.
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.
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.
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.
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, 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.
Termination is non-gracious and skips normal cleanup, unlike cancellation.
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 owning workflow has asked for cancellation, so the
activity can exit cleanly on its next heartbeat.
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: DurableWorkflowError, ImportError
Raised when the core avro runtime dependency is unavailable.