dapr · cicoyle · Apr 6, 2026 · Apr 6, 2026
@@ -29,6 +29,9 @@ dapr workflow run OrderProcessingWorkflow \
   --input '{"orderId": "12345", "amount": 100.50}'
 
 # Start with a new workflow with a specific instance ID
+# Note: instance IDs cannot be reused. If a workflow with this ID
+# already exists (in any state), the request will be rejected.
+# Purge a completed workflow first to free up its instance ID.
 dapr workflow run OrderProcessingWorkflow \
   --app-id orderprocessing \
   --instance-id order-12345 \
@@ -561,6 +564,10 @@ curl -X POST "http://localhost:3500/v1.0/workflows/dapr/OrderProcessingWorkflow/
 
 Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
 
+{{% alert title="Important" color="warning" %}}
+Workflow instance IDs cannot be reused. If a workflow with the given instance ID already exists (whether running, completed, failed, or terminated), the request will be rejected. To reuse an instance ID, first purge the existing workflow using the [purge API]({{% ref "workflow_api.md#purge-workflow-request" %}}). This ensures that workflow histories remain immutable and are only removed through explicit purge operations or a configured [retention policy]({{% ref workflow-history-retention-policy.md %}}).
+{{% /alert %}}
+
 ### Terminate workflow
 
 To terminate your workflow with an ID `12345678`, run:

@@ -98,12 +98,12 @@ Each workflow actor saves its state using the following keys in the configured a
 | `inbox-NNNNNN` | A workflow's inbox is effectively a FIFO queue of _messages_ that drive a workflow's execution. Example messages include workflow creation messages, activity task completion messages, etc. Each message is stored in its own key in the state store with the name `inbox-NNNNNN` where `NNNNNN` is a 6-digit number indicating the ordering of the messages. These state keys are removed once the corresponding messages are consumed by the workflow. |
 | `history-NNNNNN` | A workflow's history is an ordered list of events that represent a workflow's execution history. Each key in the history holds the data for a single history event. Like an append-only log, workflow history events are only added and never removed (except when a workflow performs a "continue as new" operation, which purges all history and restarts a workflow with a new input). |
 | `customStatus` | Contains a user-defined workflow status value. There is exactly one `customStatus` key for each workflow actor instance. |
-| `metadata` | Contains meta information about the workflow as a JSON blob and includes details such as the length of the inbox, the length of the history, and a 64-bit integer representing the workflow generation (for cases where the instance ID gets reused). The length information is used to determine which keys need to be read or written to when loading or saving workflow state updates. |
+| `metadata` | Contains meta information about the workflow as a JSON blob and includes details such as the length of the inbox, the length of the history, and a 64-bit integer representing the workflow generation. The length information is used to determine which keys need to be read or written to when loading or saving workflow state updates. |
 
 {{% alert title="Warning" color="warning" %}}
 Workflow actor state remains in the state store even after a workflow has completed.
 Creating a large number of workflows could result in unbounded storage usage.
-To address this either purge workflows using their ID or directly delete entries in the workflow DB store.
+To address this, purge workflows using the [purge API]({{% ref "workflow_api.md#purge-workflow-request" %}}) or configure a [workflow retention policy]({{% ref workflow-history-retention-policy.md %}}) to automatically clean up completed workflow state.
 {{% /alert %}}
 
 The following diagram illustrates the typical lifecycle of a workflow actor.
@@ -122,8 +122,8 @@ To summarize:
 
 Activity actors are responsible for managing the state and placement of all workflow activity invocations.
 A new instance of the activity actor is activated for every activity task that gets scheduled by a workflow.
-The ID of the activity actor is the ID of the workflow combined with a sequence number (sequence numbers start with 0), as well as the "generation" (incremented during instances of rerunning from using `continue as new`).
-For example, if a workflow has an ID of `876bf371` and is the third activity to be scheduled by the workflow, it's ID will be `876bf371::2::1` where `2` is the sequence number, and `1` is the generation.
+The ID of the activity actor is the ID of the workflow combined with a sequence number (sequence numbers start with 0), as well as the "generation" (incremented when a workflow uses `continue as new`).
+For example, if a workflow has an ID of `876bf371` and is the third activity to be scheduled by the workflow, its ID will be `876bf371::2::1` where `2` is the sequence number, and `1` is the generation.
 If the activity is scheduled again after a `continue as new`, the ID will be `876bf371::2::2`.
 
 No state is stored by activity actors, and instead all resulting data is sent back to the parent workflow actor.

@@ -84,7 +84,13 @@ dapr workflow resume wf-12345 \
 
 Each workflow you define has a type name, and individual executions of a workflow require a unique _instance ID_. Workflow instance IDs can be generated by your app code, which is useful when workflows correspond to business entities like documents or jobs, or can be auto-generated UUIDs. A workflow's instance ID is useful for debugging and also for managing workflows using the [Workflow APIs]({{% ref workflow_api.md %}}).
 
-Only one workflow instance with a given ID can exist at any given time. However, if a workflow instance completes or fails, its ID can be reused by a new workflow instance. Note, however, that the new workflow instance effectively replaces the old one in the configured state store.
+Only one workflow instance with a given ID can exist at any given time. Attempting to create a new workflow instance with the same ID as an existing instance will result in an error, regardless of whether the existing instance is running or has completed.
+
+{{% alert title="Important" color="warning" %}}
+As of v1.18, workflow instance ID reuse is no longer supported. Previously, if a workflow instance completed or failed, its ID could be reused by a new workflow instance. This is no longer the case. Workflow histories are immutable records and must not be overwritten through workflow creation. To remove a completed workflow's state and free up its instance ID, use the [purge API]({{% ref "workflow_api.md#purge-workflow-request" %}}) or configure a [workflow retention policy]({{% ref workflow-history-retention-policy.md %}}). After purging, the instance ID can be used for a new workflow instance.
+
+The instance ID reuse policy option that was previously available in some SDKs (allowing actions like `IGNORE` or `TERMINATE` on ID conflicts) has also been removed.
+{{% /alert %}}
 
 ### Workflow replay
 

@@ -70,6 +70,7 @@ After announcing a future breaking change, the change will happen in 2 releases
 | NATS Streaming PubSub Component                                                                                                                                                                                                                                                                             | 1.11.0                   | 1.13.0         |
 | Workflows API Alpha1 `/v1.0-alpha1/workflows` being deprecated in favor of Workflow Client                                                                                                                                                                                                                  | 1.15.0                   | 1.17.0         |
 | Migration of `http-max-request-size` flags/annotations to `max-body-size`. See [How-To: Handle larger body requests]({{% ref increase-request-size.md %}})                                                                                                                                                  | 1.14.0                   | 1.17.0         |
+| Removal of workflow instance ID reuse policy. Workflow instance IDs can no longer be reused once a workflow completes or fails. This prevents the history of a completed workflow from being overwritten. Users must use a unique instance ID for each new workflow execution.                                 | 1.18.0                   | 1.18.0         |
 
 ## Related links
 

@@ -25,6 +25,10 @@ POST http://localhost:<daprPort>/v1.0/workflows/<workflowComponentName>/<workflo
 
 Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
 
+{{% alert title="Important" color="warning" %}}
+Workflow instance IDs cannot be reused. If a workflow with the given instance ID already exists (in any state), the request will be rejected. To reuse an instance ID, first purge the workflow using the [purge API]({{% ref "workflow_api.md#purge-workflow-request" %}}). See [workflow identity]({{% ref "workflow-features-concepts.md#workflow-identity" %}}) for more details.
+{{% /alert %}}
+
 ### URL parameters
 
 Parameter | Description
@@ -43,6 +47,7 @@ Code | Description
 ---- | -----------
 `202`  | Accepted
 `400`  | Request was malformed
+`409`  | A workflow with the given instance ID already exists
 `500`  | Request formatted correctly, error in dapr code
 
 ### Response content