skip to content

A Cloudflare onboarding Workflow instance ended errored at its charge step; how do you inspect it and get that user's run going again?

level: seniorimportance: should knowfreq 30%

answer

  1. status() carries the error
  2. describe shows every attempt
  3. fix first, then rerun
  4. restart, not create
  5. from a named step

basics

~20 s

Read instance.status() or wrangler workflows instances describe to see the error and each step's attempts, fix the cause, then call restart() on that instance, optionally from the failed step; create() with the same ID throws while the instance is retained.

solid answer

~50 s

`env.ONBOARDING.get(id)` then `status()` returns `status: "errored"` with an `error` object holding `name` and `message`. `wrangler workflows instances describe onboarding <id>` shows each step with its start, end, attempts and output, so you can see that account creation succeeded and every charge attempt failed. Fix the cause first, such as a rotated payment API key or a code bug, and deploy. Then rerun the same instance with `restart()`. As of 2026, `restart({ from: { name: "charge first invoice" } })`, or the CLI's `--from-step-name`, keeps the cached results of earlier steps and re-executes only that step and those after it, so the account is not created again. `create()` with the same ID throws while the errored instance is retained (30 days by default on Workers Paid), and `resume()` only continues a paused instance. `terminate()` stops a running one.

code

bash · 3 lines
bash
npx wrangler workflows instances list onboarding --status errored
npx wrangler workflows instances describe onboarding signup-42
npx wrangler workflows instances restart onboarding signup-42 --from-step-name "charge first invoice"

go deeper

for a junior

Know that status() reports errored with an error message and that wrangler workflows instances describe shows each step's result.

for a middle

Explain the status values and which instance methods apply to each, and why create() with a used ID throws while restart() reruns it.

for a senior

Work the incident: read the step history, fix and deploy, restart from the failed step so earlier side effects are not repeated, and confirm the restarted step is idempotent.

for a principal

Set the operating rules for failed runs: who may restart or terminate production instances, retention long enough to investigate, and which errors the Workflow must handle itself instead of erroring.

## Reading what went wrong An **errored** instance in **Cloudflare Workflows** is one whose `run()` let an exception escape: a step used up its retries, a step threw `NonRetryableError`, a `waitForEvent()` timed out, or code between steps threw. The instance keeps its full history for its retention period, which is 30 days by default on Workers Paid and 3 days on Workers Free, adjustable with `default_retention` on the binding or `retention` on `create()`. Two views of it: - **From code:** `const instance = await env.ONBOARDING.get(id); await instance.status()` returns `{ status: "errored", error: { name, message }, output }`. For a Worker with a compatibility date from 2026-05-14, a `NonRetryableError` keeps its own `name` and `message` here; with an older date the message is replaced by a generic "terminated, as a step threw an NonRetryableError" text. - **From the CLI:** `wrangler workflows instances describe onboarding <id>` prints every step, its type, start and end, whether it succeeded, its attempts and its output (`--step-output` and `--truncate-output-limit` control that part). `wrangler workflows instances list onboarding --status errored` finds every failed instance at once. Read the step list before acting. In the onboarding case it typically shows `create account` and `send welcome email` succeeded, and `charge first invoice` failed on every attempt with the same message, which points to a cause outside the Workflow: an expired API key, a wrong price ID. ## Statuses and what you can do in each | Status | Meaning | Useful actions | |---|---|---| | `queued` | Created, waiting for a concurrency slot | `terminate()` | | `running` | Executing steps | `pause()`, `terminate()` | | `waiting` | Sleeping, retrying later or waiting for an event | `sendEvent()`, `pause()`, `terminate()` | | `paused` | Stopped by `pause()` | `resume()`, `terminate()` | | `errored` | Ended by an uncaught error | `restart()`, `delete()` | | `complete` | `run()` returned | `restart()`, `delete()` | | `terminated` | Stopped by `terminate()` | `restart()`, `delete()` | `terminate()` throws on an instance that is already errored, terminated or complete, and `resume()` is for paused instances. Neither revives an errored run. ## Getting the run going again 1. **Fix the cause** and deploy. A restart without a fix fails the same way. 2. **Choose where to restart.** `await instance.restart()` reruns the instance from the beginning. Since 2026, `await instance.restart({ from: { name: "charge first invoice" } })` reuses the cached results of every earlier step and re-executes only the named step and what follows. Add `count` when the name repeats in a loop, and `type` (`"do"`, `"sleep"` or `"waitForEvent"`) when a sleep or wait shares the name. The call throws if no matching step is in the instance's history. 3. **Do it from the CLI** when there is no admin route: `wrangler workflows instances restart onboarding <id> --from-step-name "charge first invoice"`, with `--from-step-count` and `--from-step-type` for the same disambiguation. 4. **Watch it** with `status()` or `describe` until it reaches `complete`. Restarting from the failed step is what keeps the user from getting a second account and a second welcome email. Even so, the charge step itself must be idempotent, because its earlier attempts may have reached the payment provider. ## Things that look like fixes but are not - `create({ id })` with the old ID throws while the errored instance is retained; a new random ID would start over from account creation. - `resume()` on an errored instance does not rerun anything; it applies to paused instances. - `delete()` removes the instance and its stored state, which also deletes the evidence. Keep that for clean-up after the user is sorted. - Raising `retries.limit` and waiting does nothing for an instance that has already errored; the new config applies to runs that reach the step again. ## Preventing the next one - Keep errored instances long enough to investigate: `default_retention` on the binding, with `error_retention` (for example `"7 days"`), or `retention.errorRetention` on `create()`, never exceeding the account's limit. - Add a known permanent failure to the code as a `NonRetryableError` with a clear message, so the next errored instance explains itself in `status()`. Catch what you can handle inside `run()`: a declined card becomes a `try...catch` that marks the account unbilled instead of erroring the instance. Register rollback options on steps that need compensation, and use `terminate({ rollback: true })` when stopping a run that has already done external work.

  • What exactly does restarting from a step reuse, and what does it run again?
    Every step that started before the named one keeps its stored result, so on the new pass those `step.do()` calls return instantly without running their callbacks. The named step and every step after it run again. Code between steps runs again regardless, as on any pass of `run()`. Use `count` or `type` in `from` when the name occurs more than once.
  • When would you terminate an instance instead of letting it run or restarting it?
    When it should not continue at all: a user deletes their account while the instance is waiting out the trial, or a bad release started runs that would charge wrongly. `terminate()` stops a running, waiting, queued or paused instance. `terminate({ rollback: true })` first runs the rollback handlers registered by completed steps, such as refunding a charge, so the stop is also compensated.

  • Calling create() again with the errored instance's ID starts a fresh run.
  • resume() is the way to retry an instance that ended errored.
  • Restarting an instance always runs it from the first step again.
  • Deleting the errored instance is a harmless first step before rerunning it.
  • Raising retries.limit in a new deploy makes an errored instance try again.

Assumes Workflows and Wrangler 4 as of 2026-10-10; restarting from a named step (restart({ from }) and --from-step-name) and terminate's rollback option are 2026 additions, and a NonRetryableError keeps its own message in status() only for compatibility dates from 2026-05-14.