A Cloudflare onboarding Workflow instance ended errored at its charge step; how do you inspect it and get that user's run going again?
answer
- status() carries the error
- describe shows every attempt
- fix first, then rerun
- restart, not create
- from a named step
basics
~20 sRead 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 linesnpx 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
Know that status() reports errored with an error message and that wrangler workflows instances describe shows each step's result.
Explain the status values and which instance methods apply to each, and why create() with a used ID throws while restart() reruns it.
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.
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.