Cosmetic consistency pass on remaining bare throws

[pranaygp]

Summary

Phase 6 of the friendlier-errors stack. A small consistency pass converting the last ergonomically-important bare throw new Error(...) sites in @workflow/core to structured error classes and friendlier messages.

• Internal invariants now throw WorkflowRuntimeError so describeError attributes them to the SDK, not the user:
  • workflow.ts: missing startedAt timestamp (should not happen)
  • vm/index.ts: crypto.subtle.generateKey() disabled inside the workflow VM — now explains why and points to step functions
  • step/get-closure-vars.ts: closure-vars accessed outside a step context
  • global.ts (ENOTSUP): explains the workflow-VM constraint and suggests moving the call to a step function
• defineHook().resume(): schema validation failures are rendered as a readable list (at "field": <message>) instead of a raw JSON dump.
• Test + snapshot updated for the two changed messages.

Manual test plan

Using workbench/nextjs-turbopack — pnpm dev and watch the terminal.

• Zod schema failure on defineHook().resume() — the headline user-visible change:

  import { z } from 'zod';
  import { defineHook } from 'workflow';
  
  export const paymentHook = defineHook<{ amount: number }>({
    schema: z.object({ amount: z.number().positive() }),
  });

  Call paymentHook.resume(token, { amount: -5 }) from a server route. Expect a readable bulleted list of validation issues — one line per issue with the field path and message (at "amount": Number must be greater than 0) — NOT a raw JSON dump of ZodError.issues.

• crypto.subtle.generateKey() inside workflow VM — call it from a "use workflow" function:

  export async function broken() {
    'use workflow';
    await crypto.subtle.generateKey({name: 'AES-GCM', length: 256}, true, ['encrypt']);
  }

  Expect a clear message explaining why it's disabled in the VM and pointing at "move this into a step function".

• WorkflowRuntimeError → 'sdk' attribution — reusing Phase 5 behavior: confirm the log for the above test includes errorAttribution: 'sdk' (not 'user'). Internal invariants should be framed as "this is us, not you."

• Non-Zod schema (e.g. valibot) — if you use a non-Zod schema validator, confirm the list rendering still works via the shared error-shaping path.

• Rare internal invariants — these only trip on severe bugs; not generally testable by hand. Covered by unit tests.

Unit tests

• pnpm --filter @workflow/core exec vitest run src/define-hook.test.ts src/vm/index.test.ts src/describe-error.test.ts
• Pre-existing DOMException / world.streams failures still match baseline

---

📚 Friendlier errors stack

Multi-PR initiative inspired by @Schniz's stalled #706:

#	PR	Phase	Summary
1	#1831	Phase 1 + 2	Ansi rendering primitives + context-violation errors
2	#1832	Phase 3	Structured logger metadata; folds in #1812
3	#1836	Phase 4	SerializationError at serialization / stream / encryption boundaries
4	#1837	Phase 5	Presentation-only user vs SDK attribution (describeError)
5	→ this PR (#1838)	Phase 6	Consistency pass on remaining bare throw new Error(...) sites
6	#1839	Phase 7 foundation	Data-driven describeRunError + public subpath
7	#1840	Phase 8	WorkflowBuildError + applications in @workflow/builders
8	#1849	Followups	Drop functionName leak, simplify docs framing, redirect stack to user code

Each PR is stacked on the previous one; merge in order.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
example-nextjs-workflow-turbopack	Ready	Preview, Comment	Apr 24, 2026 1:24am
example-nextjs-workflow-webpack	Ready	Preview, Comment	Apr 24, 2026 1:24am
example-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-astro-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-express-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-fastify-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-hono-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-nitro-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-nuxt-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-sveltekit-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workbench-vite-workflow	Ready	Preview, Comment	Apr 24, 2026 1:24am
workflow-docs	Ready	Preview, Comment, Open in v0	Apr 24, 2026 1:24am
workflow-swc-playground	Ready	Preview, Comment	Apr 24, 2026 1:24am
workflow-web	Ready	Preview, Comment	Apr 24, 2026 1:24am

[changeset-bot]

🦋 Changeset detected

Latest commit: d8b41c0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
@workflow/core	Patch
@workflow/builders	Patch
@workflow/cli	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/vitest	Patch
@workflow/web-shared	Patch
@workflow/web	Patch
workflow	Patch
@workflow/world-testing	Patch
@workflow/astro	Patch
@workflow/nest	Patch
@workflow/rollup	Patch
@workflow/sveltekit	Patch
@workflow/vite	Patch
@workflow/nuxt	Patch
@workflow/ai	Patch

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

[github-actions]

🧪 E2E Test Results

❌ Some tests failed

Summary

	Passed	Failed	Skipped	Total
❌ 💻 Local Development	1052	2	86	1140
✅ 📦 Local Production	1054	0	86	1140
✅ 🐘 Local Postgres	1054	0	86	1140
✅ 🪟 Windows	95	0	0	95
✅ 📋 Other	267	0	18	285
Total	3522	2	276	3800

❌ Failed Tests

💻 Local Development (2 failed)

vite-stable (2 failed):

• error handling error propagation step errors basic step error preserves message and stack trace
• error handling error propagation step errors cross-file step error preserves message and function names in stack

Details by Category

❌ 💻 Local Development

App	Passed	Failed	Skipped
✅ astro-stable	89	0	6
✅ express-stable	89	0	6
✅ fastify-stable	89	0	6
✅ hono-stable	89	0	6
✅ nextjs-turbopack-canary	76	0	19
✅ nextjs-turbopack-stable	95	0	0
✅ nextjs-webpack-canary	76	0	19
✅ nextjs-webpack-stable	95	0	0
✅ nitro-stable	89	0	6
✅ nuxt-stable	89	0	6
✅ sveltekit-stable	89	0	6
❌ vite-stable	87	2	6

✅ 📦 Local Production

App	Passed	Failed	Skipped
✅ astro-stable	89	0	6
✅ express-stable	89	0	6
✅ fastify-stable	89	0	6
✅ hono-stable	89	0	6
✅ nextjs-turbopack-canary	76	0	19
✅ nextjs-turbopack-stable	95	0	0
✅ nextjs-webpack-canary	76	0	19
✅ nextjs-webpack-stable	95	0	0
✅ nitro-stable	89	0	6
✅ nuxt-stable	89	0	6
✅ sveltekit-stable	89	0	6
✅ vite-stable	89	0	6

✅ 🐘 Local Postgres

App	Passed	Failed	Skipped
✅ astro-stable	89	0	6
✅ express-stable	89	0	6
✅ fastify-stable	89	0	6
✅ hono-stable	89	0	6
✅ nextjs-turbopack-canary	76	0	19
✅ nextjs-turbopack-stable	95	0	0
✅ nextjs-webpack-canary	76	0	19
✅ nextjs-webpack-stable	95	0	0
✅ nitro-stable	89	0	6
✅ nuxt-stable	89	0	6
✅ sveltekit-stable	89	0	6
✅ vite-stable	89	0	6

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack	95	0	0

✅ 📋 Other

App	Passed	Failed	Skipped
✅ e2e-local-dev-nest-stable	89	0	6
✅ e2e-local-postgres-nest-stable	89	0	6
✅ e2e-local-prod-nest-stable	89	0	6

---

📋 View full workflow run

---

❌ Some E2E test jobs failed:

• Vercel Prod: failure
• Local Dev: failure
• Local Prod: success
• Local Postgres: success
• Windows: success

Check the workflow run for details.

[Copilot]

Pull request overview

This PR continues the “friendlier-errors” series by replacing a few remaining bare throw new Error(...) sites in @workflow/core with more structured WorkflowRuntimeError throws and improving schema-validation error readability in defineHook().resume().

Changes:

• Converted several internal invariant/VM-constraint error throws to WorkflowRuntimeError for consistent SDK attribution via describeError.
• Improved defineHook().resume() schema validation failures to render as a readable multi-line list rather than a JSON dump.
• Updated unit tests/snapshots to match the new error messages.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/core/src/workflow.ts	Uses WorkflowRuntimeError for missing startedAt invariant.
packages/core/src/vm/index.ts	Throws WorkflowRuntimeError with actionable guidance for crypto.subtle.generateKey() in the workflow VM.
packages/core/src/vm/index.test.ts	Updates assertions to match the new generateKey() error message.
packages/core/src/step/get-closure-vars.ts	Uses WorkflowRuntimeError when closure vars are accessed outside step context.
packages/core/src/global.ts	Makes ENOTSUP() throw WorkflowRuntimeError with clearer VM/step guidance.
packages/core/src/define-hook.ts	Formats schema validation issues into a readable list before throwing.
packages/core/src/define-hook.test.ts	Updates inline snapshot for the new formatted validation error.
.changeset/friendlier-errors-consistency.md	Adds a patch changeset describing the consistency/error-message changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pranaygp]

Stacked: #1839 — Phase 7 foundation, data-driven describeRunError + public subpath

[pranaygp]

Superseded by #1849 — consolidated friendlier-errors PR with all 8 phases + follow-up fixes (ANSI leak, non-retry semantics, shared captureStackTrace helper).