Skip to content

Workflow docs: instance ID reuse requires the whole workflow tree be terminal#5244

Open
JoshVanL wants to merge 1 commit into
dapr:v1.18from
JoshVanL:workflow-instance-id-reuse
Open

Workflow docs: instance ID reuse requires the whole workflow tree be terminal#5244
JoshVanL wants to merge 1 commit into
dapr:v1.18from
JoshVanL:workflow-instance-id-reuse

Conversation

@JoshVanL

Copy link
Copy Markdown
Contributor

The workflow identity docs added for the 1.18 reuse policy removal stated that creating a workflow whose instance ID already exists is rejected in any state, including completed. That never matched the runtime: recreating an instance in a terminal state has been allowed since the workflow engine was introduced, and remains so.

Document the contract as enforced from 1.18.2: an instance ID is reusable only once the existing workflow and every child workflow it created, checked recursively, has reached a terminal state (COMPLETED, FAILED, or TERMINATED); otherwise the create request is rejected with a 409 conflict naming the child workflow that is not yet terminal. Purging a workflow (or a retention policy) frees its instance ID. During a rolling upgrade, children hosted by older sidecars are verified only for their own status, so the recursive guarantee applies once all sidecars run a version with the check.

Also update the breaking-changes page: the 1.18.0 removal entry now notes that SDK options still exposing the reuse policy (such as reuse_id_policy in the Python SDK) are deprecated and silently ignored by 1.18+ runtimes, and a new 1.18.2 entry records the terminal-tree requirement.

Thank you for helping make the Dapr documentation better!

Please follow this checklist before submitting:

  • Commits are signed with Developer Certificate of Origin (DCO - learn more)
  • Read the contribution guide
  • Commands include options for Linux, MacOS, and Windows within tabpane
  • New file and folder names are globally unique
  • Page references use shortcodes instead of markdown or URL links
  • Images use HTML style and have alternative text
  • Places where multiple code/command options are given have tabpane

In addition, please fill out the following to help reviewers understand this pull request:

Description

Issue reference

…be terminal

The workflow identity docs added for the 1.18 reuse policy removal
stated that creating a workflow whose instance ID already exists is
rejected in any state, including completed. That never matched the
runtime: recreating an instance in a terminal state has been allowed
since the workflow engine was introduced, and remains so.

Document the contract as enforced from 1.18.2: an instance ID is
reusable only once the existing workflow and every child workflow it
created, checked recursively, has reached a terminal state (COMPLETED,
FAILED, or TERMINATED); otherwise the create request is rejected with
a 409 conflict naming the child workflow that is not yet terminal.
Purging a workflow (or a retention policy) frees its instance ID.
During a rolling upgrade, children hosted by older sidecars are
verified only for their own status, so the recursive guarantee applies
once all sidecars run a version with the check.

Also update the breaking-changes page: the 1.18.0 removal entry now
notes that SDK options still exposing the reuse policy (such as
reuse_id_policy in the Python SDK) are deprecated and silently ignored
by 1.18+ runtimes, and a new 1.18.2 entry records the terminal-tree
requirement.

Signed-off-by: joshvanl <me@joshvanl.dev>
@JoshVanL JoshVanL requested review from a team as code owners July 13, 2026 10:45
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