Uh oh!
There was an error while loading. Please reload this page.
Presentation-only user vs SDK error attribution - #1837
Conversation
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests💻 Local Development (2 failed)vite-stable (2 failed):
Details by Category❌ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
There was a problem hiding this comment.
Pull request overview
Adds a new presentation-only error description helper in @workflow/core to enrich runtime/step terminal logs with user-vs-SDK attribution and (when available) class-aware hints, without changing persisted error classification or event data.
Changes:
- Introduce
describeError()returning{ attribution, errorCode, hint? }based on existing error classes. - Add
errorAttribution(and optionalhint) metadata to step-failure and run-failure log sites. - Add unit tests for the attribution matrix and a changeset entry.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/core/src/runtime/step-handler.ts | Enriches step failure/max-retry logs with attribution + optional hint. |
| packages/core/src/runtime.ts | Enriches fatal-setup and run-failure logs with attribution + optional hint. |
| packages/core/src/describe-error.ts | New helper implementing attribution/hint logic. |
| packages/core/src/describe-error.test.ts | Unit tests validating attribution for key error types. |
| .changeset/friendlier-error-attribution.md | Release note for new helper + logging metadata changes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| export function describeError(err: unknown): ErrorDescription { | ||
| const errorCode = classifyRunError(err); | ||
| const name = err instanceof Error ? err.name : undefined; | ||
| if (SerializationError.is(err)) { | ||
| return { | ||
| attribution: 'user', | ||
| errorCode, | ||
| hint: 'A value passed across a workflow/step boundary could not be serialized. See the error message for the offending path and the Learn More link for details.', | ||
| }; | ||
| } | ||
| if (name && CONTEXT_ERROR_NAMES.has(name)) { | ||
| return { | ||
| attribution: 'user', | ||
| errorCode, | ||
| hint: 'A workflow-only or step-only API was called from the wrong context. The error message includes the exact API and how to move the call.', | ||
| }; | ||
| } | ||
| if (err instanceof WorkflowRuntimeError) { | ||
| return { | ||
| attribution: 'sdk', | ||
| errorCode, | ||
| hint: 'This is an internal workflow SDK error, not a bug in your code. If it keeps happening, please report it with the stack trace and the runId.', | ||
| }; | ||
| } | ||
| if (errorCode === RUN_ERROR_CODES.REPLAY_TIMEOUT) { | ||
| return { | ||
| attribution: 'sdk', | ||
| errorCode, | ||
| hint: 'The workflow replay took too long. This usually means the event log is unusually large or the workflow function is doing heavy synchronous work between step boundaries.', | ||
| }; | ||
| } | ||
| if (errorCode === RUN_ERROR_CODES.MAX_DELIVERIES_EXCEEDED) { | ||
| return { | ||
| attribution: 'sdk', | ||
| errorCode, | ||
| hint: 'The workflow queue exceeded its max-delivery budget. This usually indicates a persistent runtime failure — check the most recent stack traces for the underlying cause.', | ||
| }; | ||
| } |
There was a problem hiding this comment.
describeError() currently derives errorCode exclusively via classifyRunError(), which only returns USER_ERROR or RUNTIME_ERROR. That makes the REPLAY_TIMEOUT and MAX_DELIVERIES_EXCEEDED branches unreachable, so the SDK attribution/hints for those codes will never be produced. Consider changing the API to accept a precomputed RunErrorCode (or introducing a describeErrorCode() helper) and updating call sites that have these codes but no thrown error to use it; add tests covering those paths.
There was a problem hiding this comment.
Fixed in 3dd68cc — describeError now takes an optional errorCode parameter (see the MAX_DELIVERIES_EXCEEDED / REPLAY_TIMEOUT call sites in runtime.ts). Callers that already know the code pass it in; the internal branches match on that precomputed code, so they're no longer unreachable. Three new tests cover the paths.
| const CONTEXT_ERROR_NAMES = new Set([ | ||
| 'NotInWorkflowContextError', | ||
| 'NotInStepContextError', | ||
| 'NotInWorkflowOrStepContextError', | ||
| 'UnavailableInWorkflowContextError', | ||
| ]); | ||
| /** | ||
| * Describe an error for user-facing presentation. Purely informational — | ||
| * does not change any persisted event data or error classification used by | ||
| * the runtime. | ||
| * | ||
| * The attribution here is more nuanced than `classifyRunError`: | ||
| * | ||
| * - `SerializationError` is technically raised by the SDK, but it almost | ||
| * always points at something the caller did (passed a non-serializable | ||
| * value, didn't register a class). We attribute it to the user. | ||
| * - Context-violation errors (`NotInWorkflowContextError`, etc.) likewise | ||
| * describe a user mistake. | ||
| * - `WorkflowRuntimeError` (and subclasses like `StepNotRegisteredError`) | ||
| * indicates an internal SDK invariant broke — surface that as `sdk`. | ||
| */ | ||
| export function describeError(err: unknown): ErrorDescription { | ||
| const errorCode = classifyRunError(err); | ||
| const name = err instanceof Error ? err.name : undefined; | ||
| if (SerializationError.is(err)) { | ||
| return { | ||
| attribution: 'user', | ||
| errorCode, | ||
| hint: 'A value passed across a workflow/step boundary could not be serialized. See the error message for the offending path and the Learn More link for details.', | ||
| }; | ||
| } | ||
| if (name && CONTEXT_ERROR_NAMES.has(name)) { | ||
| return { | ||
| attribution: 'user', | ||
| errorCode, | ||
| hint: 'A workflow-only or step-only API was called from the wrong context. The error message includes the exact API and how to move the call.', | ||
| }; |
There was a problem hiding this comment.
describeError() detects context-violation errors by comparing err.name against a string set. Since the concrete context error classes live in ./context-errors.ts, using instanceof checks (or a shared type guard) would be more robust and would fail at compile-time if those classes are renamed, instead of silently losing attribution/hints.
There was a problem hiding this comment.
Fixed in 3dd68cc — describeError now detects context-violation errors with instanceof against the concrete classes (NotInWorkflowContextError et al.) rather than a string Set of names, so renames can't silently break the classification.
| const errorCode = classifyRunError(err); | ||
| const description = describeError(err); | ||
| const framing = | ||
| description.attribution === 'sdk' | ||
| ? `Workflow "${workflowName}" failed due to an SDK runtime error` | ||
| : `Workflow "${workflowName}" threw`; | ||
| // Use the stack as the primary message so it shows up | ||
| // in flattened logs without structured metadata. | ||
| runLogger.error( | ||
| errorStack || 'Unknown error encountered in workflow', | ||
| `${framing}\n${errorStack || 'Unknown error encountered in workflow'}`, | ||
| { | ||
| errorCode, | ||
| errorAttribution: description.attribution, | ||
| errorName, | ||
| errorMessage, | ||
| ...(description.hint ? { hint: description.hint } : {}), | ||
| } |
There was a problem hiding this comment.
In this failure path errorCode is computed via classifyRunError(err) and describeError(err) recomputes it internally. Consider passing the already-computed errorCode into describeError (or returning attribution/hint separately) to avoid duplicated work and guarantee the logged errorCode and the description stay in sync if the classification logic evolves.
There was a problem hiding this comment.
Addressed in 3dd68cc — the call site in runtime.ts now passes the precomputed errorCode into describeError(err, errorCode), so classifyRunError is only called once.
| @@ -0,0 +1,11 @@ | |||
| --- | |||
| '@workflow/core': patch | |||
There was a problem hiding this comment.
Changeset frontmatter uses single quotes around the package name, but other changesets in this repo consistently use double quotes (YAML string). For consistency (and to match existing tooling expectations), switch this to "@workflow/core": patch.
| '@workflow/core': patch | |
| "@workflow/core": patch |
There was a problem hiding this comment.
Fixed in 3dd68cc — single-quoted frontmatter switched to double-quoted.
pranaygp
commented
Apr 23, 2026
Stacked: #1838 — Phase 6, cosmetic consistency pass on remaining bare throws |
c954c4c to
351d330CompareAdd describeError() that derives attribution and class-aware hints from existing error classes + RUN_ERROR_CODES — no event data changes. Wire into step failures, max-delivery exhaustion, run failures, and fatal setup errors so terminal logs include errorAttribution and a hint for known error types. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- `describeError(err, errorCode?)` now accepts an optional precomputed `RunErrorCode`. `classifyRunError(err)` only narrows to USER_ERROR / RUNTIME_ERROR, so the REPLAY_TIMEOUT and MAX_DELIVERIES_EXCEEDED branches were previously unreachable from the step / run failure log sites. Callers that know the failure category (runtime.ts for replay timeout and max-deliveries exhaustion) now pass the code in. - Context-violation checks use `instanceof` against the actual classes from context-errors.ts instead of a name-string set. Type-safe + survives class renames. - Wire the new hints through to the REPLAY_TIMEOUT and MAX_DELIVERIES_EXCEEDED log sites so those branches actually render a hint now. - 3 new tests cover the reachable code paths + precomputed-code override. - Changeset frontmatter switched to double quotes per repo convention.
eb171bb to
3dd68ccCompare🦋 Changeset detectedLatest commit: 3dd68cc The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
pranaygp
commented
Apr 24, 2026
Superseded by #1849 — consolidated friendlier-errors PR with all 8 phases + follow-up fixes (ANSI leak, non-retry semantics, shared captureStackTrace helper). |
Summary
Phase 5 of the friendlier-errors stack. Adds a presentation-only helper
describeError()that computes user vs SDK attribution and class-aware hints from existing error classes andRUN_ERROR_CODES. No event data or persisted error classification is affected.packages/core/src/describe-error.tsreturning{ attribution, errorCode, hint? }userfor plain errors,SerializationError, and context-violation errors (NotInWorkflowContextError, etc.)sdkforWorkflowRuntimeError(and subclasses likeStepNotRegisteredError), replay timeouts, and max-delivery exhaustionerrorAttributionmetadata and ahintfield for known error types.Motivated by a real customer case where a vendor's 503 looked like an SDK failure.
Manual test plan
Using
workbench/nextjs-turbopack—pnpm devand watch the terminal. Each test checks the structured metadata in the[workflow-sdk]log at step/run-failure time.User error →
attribution: 'user', no hint — throw plainError('boom')from a step. Confirm the log metadata includeserrorAttribution: 'user'and nohintfield (plain user errors get no hint — stack is already useful).SerializationError→'user'+ serialization hint — reuse the "unregistered class" test from Phase 4. Log metadata should includeerrorAttribution: 'user'andhint: 'A value passed across a workflow/step boundary could not be serialized. See the error message for the offending path and the Learn More link for details.'Context-violation →
'user'+ context hint — callcreateHook()from a route. Log metadata should includeerrorAttribution: 'user'andhint: 'A workflow-only or step-only API was called from the wrong context. The error message includes the exact API and how to move the call.'WorkflowRuntimeError→'sdk'+ runtime hint — hard to trigger accidentally; throw one directly:Expect
errorAttribution: 'sdk'andhint: 'This is an internal workflow SDK error, not a bug in your code. If it keeps happening, please report it with the stack trace and the runId.'Replay timeout →
'sdk'+ replay hint — setWORKFLOW_REPLAY_TIMEOUT_MS=50, run a non-trivial workflow. After retries exhaust, expecterrorAttribution: 'sdk'andhint: 'The workflow replay took too long…'.Max-delivery exhaustion →
'sdk'+ max-delivery hint — write a step that always throws. After the queue's max-delivery budget exhausts, expecterrorAttribution: 'sdk'andhint: 'The workflow queue exceeded its max-delivery budget…'.Attribution applies at all four log sites — confirm the log contains
errorAttribution+ optionalhintat:Unit tests
pnpm --filter @workflow/core exec vitest run src/describe-error.test.ts(6 tests)classify-error.test.ts📚 Friendlier errors stack
Multi-PR initiative inspired by @Schniz's stalled #706:
Ansirendering primitives + context-violation errorsSerializationErrorat serialization / stream / encryption boundariesdescribeError)throw new Error(...)sitesdescribeRunError+ public subpathWorkflowBuildError+ applications in@workflow/buildersfunctionNameleak, simplify docs framing, redirect stack to user codeEach PR is stacked on the previous one; merge in order.
🤖 Generated with Claude Code