Errors¶
Typed exceptions raised by the Durable Workflow client and worker.
Every error exception inherits from :class: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. :class:WorkflowCancelled
and :class:ActivityCancelled inherit from :class: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
:class:asyncio.CancelledError and :class: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
A server response was an error that does not map to a typed subclass.
The HTTP status is on :attr:status, and the parsed JSON body is on
:attr:body when the server returned one.
Bases: DurableWorkflowError
A workflow finished in the failed state.
:attr: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 namespace configured on the :class:~durable_workflow.Client is unknown to the server.
Bases: DurableWorkflowError
The server rejected the request as malformed (HTTP 422).
:attr: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: 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.
Bases: DurableWorkflowError
A workflow update was rejected by the workflow's validator.
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.
:attr: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 :class: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: BaseException
A workflow was cancelled and finished in the cancelled state.
Inherits from :class:BaseException — not :class: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 :meth: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 :class:BaseException — not :class: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.