cloudflare / cloudflare/workerd

Workflows: type the errors thrown by the binding (stable codes + documented list)

Open
#6,899 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
8.7k
Forks
739
Avg merge
2d 20h
Merged PRs (30d)
174

Description

## Feature request

Give errors thrown by the Workflows binding a stable, machine-readable identity. Today `create()`, `get()`, `sendEvent()`, etc. throw a bare `Error` whose only information is a prose `message`. There is also no documented list of the errors each method can throw.

## Ask

1. A stable `code` string property (or typed error classes) on every error thrown by Workflows binding methods. No API-shape change - keep throwing, just typed.
2. A documented enumeration of those codes per method, with meaning and whether the condition is transient.
3. Nice to have: `retryable: boolean` on the error itself.

## Precedent in the platform

Newer Cloudflare products already do this - Workflows and Queues (#6834) are the outliers:

| Product | Error identity |
| --- | --- |
| D1 | Stable message constants (`D1_ERROR`, `D1_TYPE_ERROR`, ...) + documented error list with retry guidance |
| Email Service binding | String `code` properties (`E_SENDER_NOT_VERIFIED`) + documented code table |
| AI Search binding | Typed classes (`AiSearchNotFoundError`, `AiSearchInternalError`) |
| Workflows / Queues | Bare `Error`, prose message only |

## Why (concrete example)

`create()` can throw `Error("internal error")`. Without a code, a caller deciding retry-vs-drop can only string-match prose - and prose can't be classified: transient errors are an open set. We handle unknown errors conservatively (don't retry), so a transient control-plane hiccup was treated as permanent failure. With a code (`workflow.internal_error`, marked transient in docs) - or a `retryable` flag - the correct handling would have been one `if`.

The same applies to terminal states: callers today match strings like `"instance.already_exists"` to implement idempotent create, and any copy edit to those messages breaks working code silently.

Contributor guide

Open the contributing guide

Research direction

Locate the Workflows binding implementations for create(), get(), sendEvent(), and the other methods named in the request. Compare their error handling with the cited D1, Email Service, and AI Search precedents. Done means each method's errors have stable identities and documentation lists their codes, meanings, and transient status; retryable is an optional additional property.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, javascript
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.