Skip to content

docs: never catch blanket exceptions in workflow code - #33

Merged
rgamba merged 1 commit into
mainfrom
docs/no-blanket-catch-in-workflows
Sep 18, 2026
Merged

rgamba merged 1 commit into
mainfrom
docs/no-blanket-catch-in-workflows

Conversation

@rgamba

@rgamba rgamba commented Sep 18, 2026

Copy link
Copy Markdown
Member

Summary

Adds guidance to the docs site that workflow code must not catch Throwable, Exception, RuntimeException, or Error. Skipper drives execution through exceptions: waitUntil suspends a workflow by throwing an internal control-flow signal, and action failures surface as retryable or non-retryable errors that the engine needs to see. A blanket catch intercepts both and sends the workflow down a path it was never meant to take.

Where it lives

  • Error Handling & Retries gets a dedicated section, "Don't catch blanket exceptions in workflow code". It states the rule, gives the two reasons at a high level, shows a short Kotlin and Java "don't do this" example, and points to the right place for error handling: inside the action, catching concrete types. It also flags helpers that catch broadly on the caller's behalf, such as runCatching.
  • Core Concepts already had a one-line callout in the Determinism section. It now covers Exception too and links to the new section.
  • Workflow API gets a Best practices bullet next to the waitUntil docs, linking to the new section.

The full explanation lives in one place and the other pages link to it, so the rule is discoverable from wherever a reader is likely to hit the problem without repeating the rationale three times.

Testing

  • npx astro build in web/ passes, 32 pages built.
  • Verified the generated heading id dont-catch-blanket-exceptions-in-workflow-code exists in the built Error Handling page and that both cross-links in the built Core Concepts and Workflow API pages point at it.
  • The code samples use the single-argument waitUntil(condition) overload defined in Workflow.kt.

@rgamba
rgamba marked this pull request as ready for review September 18, 2026 18:50
@rgamba
rgamba merged commit 3f1ab77 into main Sep 18, 2026
10 checks passed
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.

1 participant