NonRetryableError thrown inside a Dynamic Worker is flattened crossing the runner stub, so the engine retries it

[matt-jamie-milne]

Summary

When a Dynamic Worker's WorkflowEntrypoint throws NonRetryableError (imported from cloudflare:workflows), the error loses its class crossing the RPC stub back to the dispatcher, so the Workflows engine treats it as retryable and retries the step. The failure surfaces as a plain Error.

Version: @cloudflare/dynamic-workflows@0.1.1, wrangler@4.120.1. Observed under local wrangler dev.

Repro

Dispatcher wired the documented way — createDynamicWorkflowEntrypoint, DynamicWorkflowBinding re-exported, instances created through wrapWorkflowBinding(metadata). The tenant module loaded via env.LOADER.get(id, ...) with globalOutbound: null and a single RPC-stub binding:

import { WorkflowEntrypoint } from 'cloudflare:workers'
import { NonRetryableError } from 'cloudflare:workflows'

export class WorkflowRunner extends WorkflowEntrypoint {
  async run(event, step) {
    return step.do('denied_step', async () => {
      throw new NonRetryableError('policy_violation', 'policy_violation')
    })
  }
}

Expected

The step fails immediately; the instance errors once.

Actual

The step is retried (I measured 6 attempts before the instance errored — each attempt re-entered the step and re-invoked the binding it calls). The instance's final status carries:

{ "name": "Error", "message": "policy_violation: policy_violation" }

The NonRetryableError name is gone and the constructor's (message, name) arguments appear concatenated into message, which looks like error serialization across the Workers RPC boundary rather than anything Workflows-specific.

Why it matters

NonRetryableError is the only way for tenant code to say "this cannot heal". With it unavailable, every terminal failure inside a Dynamic Workflow burns the full retry budget, and any per-attempt side effect (logging, metering, an audit record) is multiplied by the retry count.

Where it seems to originate

dispatchWorkflow ends with return runner.run(innerEvent, step) and neither it nor createDynamicWorkflowEntrypoint touches errors, so the thrown value is whatever survives the stub call. Nothing in the library appears intended to map it.

Possible resolutions

1. Have dispatchWorkflow catch errors from runner.run and rehydrate a native NonRetryableError in the dispatcher isolate (some marker would need to survive serialization).
2. Expose an error-mapping hook alongside loadRunner, so consumers can decide.
3. If preserving the class is not feasible, document the limitation and the recommended workaround.

A consumer-side workaround exists — encode retryability in the message, then wrap the runner returned from loadRunner and re-throw a native NonRetryableError in the dispatcher — but it relies on tenant-supplied strings, so a library-level answer would be better.

Not verified

I could not verify whether deployed (non-local) behaviour differs; the worker in question is local-only by design. Happy to test a suggested patch.

[matt-jamie-milne]

Correction and a sharper diagnosis after more testing — the retry behaviour is real, but my original attribution was partly wrong.

A NonRetryableError thrown from the dispatcher's own run() IS honoured. I threw one from inside loadRunner (so it never reaches the loaded worker): the instance errored after exactly 1 attempt. So Workflows honours the class at entrypoint level in local dev.

The loss is specific to a throw inside step.do in the loaded worker. The step callback executes in the Dynamic Worker; when it throws, the error crosses back to the engine's step machinery, and the retry decision is made there against a value that has already lost its class. The step then burns its full retry budget. Wrapping the runner returned from loadRunner in a try/catch does not help: that wrapper only sees the error after step.do has finished retrying.

Also worth noting: the {name: 'Error', message: '<name>: <message>'} shape in instance.status().error appears in the 1-attempt case too, so that serialization is display-only and is not itself evidence of lost retryability.

Workaround that does work, for anyone hitting this: don't throw non-retryable failures inside the step — return them as data, and throw outside the step where the class survives.

const outcome = await step.do('call', async () => {
  const result = await this.env.GATEWAY.invoke(...)
  if (result.ok) return { ok: true, value: result.value }
  if (result.failure.retryable) throw new Error(result.failure.code)
  return { ok: false, code: result.failure.code }
})
if (!outcome.ok) throw new NonRetryableError(outcome.code, outcome.code)

Measured on our side: 6 attempts (and 6 duplicate audit records) before, exactly 1 after.

That leaves the underlying request narrower than I first wrote it: a way for a Dynamic Worker to signal non-retryability from inside a step. Options might be preserving the error class across the stub boundary, or an explicit marker the step machinery understands. If the intended answer is "return, don't throw", a line in the docs would save others the same detour.

[a-robinson]

@deloreyj