cloudflare / cloudflare/workerd
Workflows: type the errors thrown by the binding (stable codes + documented list)
- 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
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