Skip to content

Conversation

axfelix
Copy link
Contributor

@axfelix axfelix commented Sep 18, 2025

Added some missing context from the error handling course to explain Activity vs Workflow Failures and Non-Retryable Errors. This should be ported to the other languages if we like it (and note that Go works a bit differently than the others).

@axfelix axfelix requested a review from a team as a code owner September 18, 2025 21:42
Copy link
Contributor

@brianmacdonald-temporal brianmacdonald-temporal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really good additions; just did a little wordsmithing.

```

Depending on your implementation, you may decide to use either method.
One reason to use the Temporal `ApplicationError` class is because it allows you to set an additional `non_retryable` parameter.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
One reason to use the Temporal `ApplicationError` class is because it allows you to set an additional `non_retryable` parameter.
An additional reason to use the Temporal `ApplicationError` class is because it allows you to set an additional `non_retryable` parameter.

Suggested this change since you already gave one valid reason; so this is another.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmmm, did I already give another reason?


## Failing Workflows {#workflow-failure}

One of the core design principles of Temporal is that an Activity Failure will never directly cause a Workflow Failure — a Workflow should never return as Failed unless deliberately.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
One of the core design principles of Temporal is that an Activity Failure will never directly cause a Workflow Failure — a Workflow should never return as Failed unless deliberately.
One of the core design principles of Temporal is that an Activity Failure will never directly cause a Workflow Failure — a Workflow should never return as Failed unless it is deliberately returned that way.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmmm. Good pointing out this wasn't clear, can we just change "deliberately" to "intentional"? Fewer words.

) from e
```

You can alternately specify a list of errors that are non-retryable in your Activity [Retry Policy](#activity-retries).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quick code sample for this here would be nice!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is anchored down to the rest of the same doc, I didn't want to overload it here.


This works differently in a Workflow than raising exceptions from Activities.
In an Activity, any Python exceptions or custom exceptions are converted to a Temporal `ApplicationError`.
In a Workflow, any exceptions that are raised other than an explicit Temporal `ApplicationError` will only fail that particular [Workflow Task](https://docs.temporal.io/tasks#workflow-task-execution) and be retried.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be good to specifically mention:

  • the difference between a Workflow Task Failure vs Workflow Execution Failure. I know you're doing this here, but calling it Workflow Task Failure might help people understand this error when it appears in the Web UI.
  • Also that Workflow Task Failures retry by default.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personal bias, but imo I think trying to explain "Workflow Task vs Workflow Execution" gets really into the weeds (it's my least favorite aspect of the actual course right now), and I deliberately tried to avoid that here. A Workflow Task is a very marginal aspect of most people's understanding of Temporal, I want to keep the emphasis on "retry" vs "return".

@brianmacdonald-temporal brianmacdonald-temporal merged commit af57b68 into main Sep 25, 2025
4 checks passed
@brianmacdonald-temporal brianmacdonald-temporal deleted the python-errors-clarification branch September 25, 2025 17:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants