Skip to main content

Workflow versioning

Because Diagrid Workflows reconstruct state by replaying history through your orchestrator code (see Durable execution), changes to that code must preserve determinism for in-flight executions. A change that's "safe" against fresh starts can still corrupt a workflow that's halfway through its history.

This page covers the rules for what is and isn't replay-safe, and the strategies teams use to evolve workflows without breaking running instances: version gates, drain and redeploy, a new workflow name, patches, and named versions.

What replay actually checks​

When a workflow resumes, the runtime walks your orchestrator code top to bottom, comparing each call (call_activity, create_timer, wait_for_external_event) to the next event in history:

  • Same call as recorded → return the recorded result, advance to the next call.
  • Different call than recorded → the runtime cannot reconcile the code with the history, and the workflow fails (typically with a non-determinism error).
New code replayed against old historyv1 codev2 codeState storehistory: validate, charge_cardvalidatecharge_cardvalidate_v2charge_cardreplay: matchreplay: mismatch
New code replayed against old historyBoth versions replay the same history from the state store. The v1 code makes the recorded calls in the recorded order; the v2 code's first call doesn't match, so the workflow fails with a non-determinism error.

So the rule of thumb is: changes that don't alter the calls already made by in-flight instances are safe; changes that do are not.

Safe changes​

You can deploy these against running workflows with no migration:

  • Add new code paths that in-flight instances will not enter. A new branch in a match / if statement, gated on a new input value or new state, is fine — existing instances will never see the gate flip.
  • Add new activities or sub-workflows after the current checkpoint. Anything that runs after what in-flight instances have already executed is replay-safe; the new calls become new history events when the workflow advances past its old checkpoint.
  • Add new external-event handlers. A new wait_for_external_event reachable only by future code paths is fine.
  • Tighten activity input or output schemas in a backwards-compatible way. Adding optional fields, never removing required ones.

Unsafe changes​

These will break in-flight executions and require a migration strategy:

  • Reordering activity calls. The order in history is the order replay expects.
  • Adding, removing, or renaming activities that in-flight instances have already scheduled. Anything that changes a call_activity already in history.
  • Changing the parameters passed to an existing activity call. The runtime keys replay on the call shape.
  • Changing the duration of a timer that an in-flight instance has already set. The recorded TimerCreated.fires_at is the source of truth; new code reading a different value desynchronises replay.
  • Reordering parallel calls in a fan-out. Even though they run in parallel, the orchestrator records them in a specific order.

When in doubt, ask: "Does this change alter any call that an existing instance has already recorded?" If yes, use one of the strategies below.

Strategy 1 — Version gates​

Branch the workflow code on a version flag passed as workflow input. Workflow input is recorded in history on the first run and replayed back on every subsequent run, so reading it inside the orchestrator is replay-safe. What is NOT safe is reading the version from an external source inside the orchestrator (env var, config file, database) — those would produce different values on replay. Old instances follow the old path; new instances follow the new path.

@wfr.workflow(name="order_processing")
def order_processing(ctx: DaprWorkflowContext, input: dict):
version = input.get("version", 1)
order = input["order"]

if version >= 2:
# New path — refactored validation + new compliance check.
valid = yield ctx.call_activity(validate_v2, input=order)
yield ctx.call_activity(compliance_check, input=order)
else:
# Old path — must remain byte-identical for in-flight v1 instances.
valid = yield ctx.call_activity(validate, input=order)

if not valid:
return {"status": "rejected"}

yield ctx.call_activity(charge_card, input=order)
return {"status": "completed"}

When starting a new workflow, callers pass version=2. Existing v1 instances continue running through the v1 branch. Eventually you remove the v1 branch — but only once you're sure no v1 instances are still running (see Strategy 2).

Strategy 2 — Drain and redeploy​

Stop starting new instances of the old version, wait for existing instances to complete (or terminate them explicitly), then deploy the new version.

  1. Deploy a build that rejects new starts of the old workflow (or routes them to the new name — see Strategy 3).
  2. Monitor in-flight instances in the Workflows console until the count drops to zero, or use the workflow CLI. Do not rely on diagrid workflow list --status running alone: it does not show stalled instances or instances that are pending. Also run diagrid workflow list without a status filter and read the status of every row, and check the stalled executions in the console.
  3. For long-running workflows that would never drain, use diagrid workflow terminate on stragglers.
  4. Deploy the new version. There are no in-flight instances against the old code, so the new code can be a clean rewrite.

This is the simplest strategy when the workflow's typical duration is short (minutes to hours).

Strategy 3 — New workflow name​

Deploy the updated logic as a new workflow name (order_processing_v2) and route new starts to it. Old instances keep running on the old name. Once the old workflow drains, retire the name.

@wfr.workflow(name="order_processing")
def order_processing_v1(ctx: DaprWorkflowContext, order: dict):
# Preserved unchanged so in-flight instances continue to replay correctly.
...

@wfr.workflow(name="order_processing_v2")
def order_processing_v2(ctx: DaprWorkflowContext, order: dict):
# New logic, free to differ arbitrarily from v1.
...

The deploy is risk-free because the v1 code is untouched. The downside is operational: two workflow names coexist until v1 drains, and any external system that starts workflows must know which name to call.

This is the safest strategy when the change is large (architectural, not just additive) or when the workflow's typical duration is long (days to weeks).

Strategy 4 — Patches​

A patch is a named branch point inside the workflow code. You give the patch a stable, unique name, and an if statement checks whether the workflow instance has applied that patch. New instances take the patched path. Instances that started before the patch existed keep the original path. Diagrid records each patch check in the instance history the first time the check runs, so replay follows the same path every time.

from dapr.ext.workflow import DaprWorkflowContext, WorkflowRuntime

wfr = WorkflowRuntime()

@wfr.workflow
def my_workflow(ctx: DaprWorkflowContext, wf_input: str):
if ctx.is_patched("use-sms"):
yield ctx.call_activity(send_sms)
else:
yield ctx.call_activity(send_email)

Follow these rules:

  • Keep the original code unchanged. In-flight instances still run it.
  • Never reuse a patch name that you already deployed to production, and never move or remove a patch. A patch name is unique within one workflow. Two workflows can use the same name.
  • Every patch is stored in the instance history, so many patches make the history larger and slow each replay.

An instance stalls, and does not fail, when you rename or remove a patch, change the order of patches, or reuse a name.

The Dapr documentation shows patches for the .NET, Go and Python SDKs. For other SDKs, check the documentation of that SDK.

Strategy 5 — Named versions​

With named versions, you register several versions of one workflow under the same name and mark one as the latest. New instances run the latest version. An instance that started on an older version keeps running on that version. The runtime does not step an instance through the versions in order, so you do not write migration code between versions.

from dapr.ext.workflow import DaprWorkflowContext, WorkflowRuntime

wfr = WorkflowRuntime()

@wfr.versioned_workflow(name="workflow", version_name="workflow_v1", is_latest=False)
def workflow_v1(ctx: DaprWorkflowContext, wf_input: str):
...

@wfr.versioned_workflow(name="workflow", version_name="workflow_v2", is_latest=True)
def workflow_v2(ctx: DaprWorkflowContext, wf_input: str):
...

Do not remove an old version while any instance, including one that waits on a long timer, still runs on it. Patches and named versions work together. Add patches for small changes. When the patches grow, copy the workflow into a new named version, remove the patches from the copy, and continue from there.

Versioning does not cover a change to the input or output type of a workflow. Return values that old and new consumers can both read, such as serialized strings, or types with optional fields.

The Dapr documentation shows named versions for the .NET, Go and Python SDKs. The registration call differs for each SDK.

Stalled instances during a rollout​

If an instance needs a workflow version or patch that the running code does not have, the instance stalls. It does not fail. This happens during a rollout, when a replica with the old code replays an instance that started on a replica with the new code, and when you remove a version that an instance still needs.

A stalled instance recovers by itself when code that matches its history runs again. Finish the rollout, or deploy code that has the missing version or patch. If an instance stays stalled, the cause is still in your code.

A stalled instance does not show in diagrid workflow list --status running. See the drain steps in Strategy 2.

Choosing a strategy​

StrategyWhen to useEffortRisk
Version gateAdditive change, both versions can coexist in the same functionLowLow — if you preserve the v1 branch byte-for-byte
Drain and redeployShort-duration workflows, willing to pause new starts brieflyLowLow — but only viable if drain is feasible
New workflow nameLarge refactor, long-duration workflows, can't risk replay corruptionMediumLowest — old code is fully isolated
PatchSmall targeted change inside a workflow that has in-flight instancesLowLow — if you never move, remove, or reuse a patch name
Named versionLarger change, or too many patches, and you want one workflow nameMediumLow — if you keep old versions until no instance uses them

For most teams, start with a patch or a version gate for small changes, and reach for a named version or a new workflow name when the refactor is significant.

See also​