docs: document error codes and remove docs typecheck import inference#1445
Open
docs: document error codes and remove docs typecheck import inference#1445
Conversation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests🌍 Community Worlds (56 failed)mongodb (3 failed):
redis (2 failed):
turso (51 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
|
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
6 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the “Errors & Retrying” documentation to explain the new run failure error codes (USER_ERROR, RUNTIME_ERROR) and how to read them from WorkflowRunFailedError.cause.code, aligning the docs with the companion runtime change in #1340.
Changes:
- Add an “Error Codes” section with a programmatic example and a code/meaning table.
- Add a callout noting where else the error code is surfaced (CLI + OTEL).
- Add a Changesets entry (currently empty/invalid).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/content/docs/foundations/errors-and-retries.mdx | Documents USER_ERROR/RUNTIME_ERROR and shows how to access err.cause.code. |
| .changeset/error-codes-docs.md | Adds a changeset file (currently missing required contents). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| | `RUNTIME_ERROR` | An internal runtime error such as a corrupted event log or missing data. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) | | ||
|
|
||
| <Callout type="info"> | ||
| The error code is also available on the run entity via the CLI (`workflow inspect runs <runId> --withData`) in the `error.code` field, and as an OTEL span attribute (`workflow.error.code`) for observability. |
Collaborator
Author
There was a problem hiding this comment.
Fixed — removed --withData and switched to npx workflow to match the rest of the docs.
.changeset/error-codes-docs.md
Outdated
Comment on lines
+1
to
+2
| --- | ||
| --- |
Collaborator
Author
There was a problem hiding this comment.
no changes needed for docs change
Collaborator
Author
There was a problem hiding this comment.
Removed the empty changeset — this is a docs-only change so no changeset is needed.
| When a workflow run fails, the error includes a `code` that classifies the failure. You can access it programmatically via the `Run` class: | ||
|
|
||
| ```typescript lineNumbers | ||
| import { WorkflowRunFailedError } from "workflow"; |
Collaborator
Author
There was a problem hiding this comment.
Fixed — added import { start } from "workflow/api" to match other docs.
Comment on lines
+144
to
+156
| When a workflow run fails, the error includes a `code` that classifies the failure. You can access it programmatically via the `Run` class: | ||
|
|
||
| ```typescript lineNumbers | ||
| import { WorkflowRunFailedError } from "workflow"; | ||
|
|
||
| const run = await start(myWorkflow, [input]); | ||
|
|
||
| try { | ||
| const result = await run.returnValue; | ||
| } catch (err) { | ||
| if (WorkflowRunFailedError.is(err)) { | ||
| console.log(err.cause.code); // "USER_ERROR" or "RUNTIME_ERROR" | ||
| console.log(err.cause.message); // The error message |
Collaborator
Author
There was a problem hiding this comment.
Good call — updated wording to "may include" and changed the inline comment to show undefined as a possible value.
- Add missing `start` import from `workflow/api` - Note that `cause.code` may be undefined for older runs - Remove invalid `--withData` flag and use `npx workflow` CLI style - Remove empty changeset (docs-only change needs no changeset) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the import-inference system that auto-added imports to doc snippets before typechecking. This was masking real issues — if a snippet imported from the wrong module or was missing an import, the typechecker silently fixed it instead of catching the bug. All 24 affected doc snippets now have explicit, correct imports that match what users would actually write. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
auto-merge was automatically disabled
March 18, 2026 22:34
Pull request was converted to draft
pranaygp
changed the title
pranaygp
commented
Mar 18, 2026
| When hitting API rate limits, use `RetryableError` with a delay: | ||
|
|
||
| ```typescript lineNumbers | ||
| import { sleep, RetryableError } from "workflow"; |
Collaborator
Author
There was a problem hiding this comment.
this example is not using sleep
Collaborator
Author
There was a problem hiding this comment.
Good catch — removed the unused sleep import. This snippet only uses RetryableError.
pranaygp
commented
Mar 18, 2026
| @@ -74,6 +78,7 @@ export async function processPayment() { | |||
| When a hook conflict occurs, awaiting the hook will throw a `WorkflowRuntimeError`. You can catch this error to handle the conflict gracefully: | |||
Collaborator
Author
There was a problem hiding this comment.
is this correct? is it not a HookConflictError? is it really just a WorkflowRuntimeError? 🤔
WorkflowRuntimeError is meant to be only for infrastructure outages/issues with an invalid workflow log - not normal behavior
Collaborator
Author
There was a problem hiding this comment.
You're right to question this. I checked the runtime code — suspension-handler.ts:342 confirms it currently rejects with WorkflowRuntimeError when a hook_conflict event is replayed. So the docs are accurate to the current behavior, but this does seem like it should be a more specific error type (e.g. HookConflictError) since WorkflowRuntimeError is meant for infrastructure issues. Want me to leave this as-is for now since it's a pre-existing doc, or file an issue for the error type change?
Collaborator
Author
There was a problem hiding this comment.
I'm doing a follow up PR to fix this and throw an actual HookConflictError but out of scope for this PR
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Collaborator
Author
|
test failures on vercel world are unrelated to docs changes 🤷🏼 |
VaguelySerious
approved these changes
Mar 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
USER_ERROR,RUNTIME_ERROR) in the errors and retries guide, including programmatic access viaWorkflowRunFailedErrorand CLI/OTEL availabilityimport-inference.tssystem was auto-adding imports to doc snippets before typechecking, which masked real issues (e.g., importingWorkflowRunFailedErrorfrom"workflow"when it's only exported from@workflow/errors). Doc snippets now typecheck exactly as users would copy-paste them.getWritable,createWebhook,createHook,defineHook,getRun,sleep,RetryableError,Agent,LanguageModel,ModelMessage, etc.Test plan
pnpm test:docspasses locally (268/268)🤖 Generated with Claude Code