"start" receives invalid workflow function — "use workflow" directive not transformed (Next.js 16 + Turbopack + Vercel World)

[jonio87]

Summary

start() throws 'start' received an invalid workflow function even though the function has a "use workflow" directive. The build correctly discovers the directive and generates the manifest (14 steps, 1 workflow), but at runtime the function is not recognized as a valid workflow.

Environment

• workflow: 4.2.0-beta.71
• Next.js: 16.1.5 (Turbopack — default bundler)
• Node: 22.12.0
• World: Vercel World (Pro plan) — also reproduced with Local World
• Platform: macOS (local) + Vercel serverless (deployed)

Configuration

// next.config.ts
import { withWorkflow } from "workflow/next";
const nextConfig = { /* ... */ } as NextConfig;
export default withWorkflow(nextConfig);

// instrumentation.ts
export async function register() {
  // No-op — Vercel World is auto-managed
}

Workflow definition

// lib/workflows/callback-pipeline.ts
import { sleep, createWebhook } from "workflow"

async function fetchLead(leadId: string) {
  "use step"
  // ...
}

// ... 13 more "use step" functions

export async function callbackPipeline(
  leadId: string,
  phone: string,
  scoreTier: string,
  leadTier: string,
) {
  "use workflow"
  // ... orchestration using steps + sleep + createWebhook
}

API route (caller)

// app/api/leads/route.ts
import { start } from "workflow/api"
import { callbackPipeline } from "@/lib/workflows/callback-pipeline"

// Inside POST handler:
await start(callbackPipeline, [leadId, phone, scoreTier, leadTier])

Build output (looks correct)

Discovering workflow directives 1920ms
Created steps bundle 109ms
Created intermediate workflow bundle 67ms
Creating webhook route
Created manifest with 14 steps, 1 workflow, and 0 classes 12ms

Generated routes exist:

├ ƒ /.well-known/workflow/v1/flow
├ ƒ /.well-known/workflow/v1/step
├ ƒ /.well-known/workflow/v1/webhook/[token]

Runtime error

[WDK] Callback pipeline start failed (non-fatal): 'start' received an invalid workflow function.
Ensure the Workflow Development Kit is configured correctly and the function includes a
'use workflow' directive.

Learn more: https://useworkflow.dev/err/start-invalid-workflow-function

What I've tried

1. Static imports (top-level import { start } from "workflow/api") — same error
2. Dynamic imports (await import("workflow/api")) — same error
3. Webpack build (NEXT_TURBOPACK=0 npx next build) — same error
4. Cleared .next cache + .workflow-data — same error
5. next start (production mode) — same error
6. Different worlds — Vercel World, Local World, Postgres World — all same error
7. Verified "use workflow" directive is present in the exported function

Suspected cause

The withWorkflow() async config function runs at build time and generates the manifest + routes, but the SWC transform that converts "use workflow" annotated functions into manifest-referenced stubs does not execute during the Turbopack build pipeline. The original function reaches start() untransformed, so start() doesn't recognize it.

This may be related to:

• a2c0c7e ("Seed lazy workflow file discovery in NextJS. Require workflow definitions to be in manifest for Vercel environments") — the manifest requirement may have introduced a regression
• d72c822 ("Fix bug where the SWC compiler prunes step-only imports in the client-mode transformation") — possibly related SWC transform issue

Workaround

Using a callback orchestrator pattern (direct function calls via an event bus) instead of WDK start(). The WDK config remains in place and is ready to re-enable once this is resolved.

[jonio87]

Additional finding: withWorkflow() build-time discovery never runs during next build

After further testing, the root cause is clearer. The withWorkflow() async config function's build-time directive discovery step never executes during next build.

Evidence

When calling withWorkflow() directly from Node.js:

Discovering workflow directives 1742ms
Created steps bundle 34ms
Created intermediate workflow bundle 14ms
Creating webhook route
Created manifest with 14 steps, 1 workflow, and 0 classes 6ms

During next build — none of these lines appear. No .workflow-data/ directory is created. The WDK routes (.well-known/workflow/v1/*) appear in the build output but the SWC transform that converts "use workflow" directives into manifest-referenced stubs doesn't run.

What withWorkflow() returns

const fn = withWorkflow(nextConfig);
typeof fn; // "function" (AsyncFunction)
fn.constructor.name; // "AsyncFunction"

It returns an async function (not a Promise). Next.js 16 should call this function to resolve the config, but the build-time side effects (directive discovery, SWC transform) don't execute.

Tried export default withWorkflow(nextConfig)() (calling it to get a Promise) — .workflow-data still not created, same runtime error.

Environment

• Next.js 16.1.5 with Turbopack (default bundler)
• Also tried NEXT_TURBOPACK=0 (webpack) — same behavior
• workflow@4.2.0-beta.71

[jonio87]

Minimal reproduction confirms: SWC transform never runs

Created a dead-simple workflow to isolate the issue:

// lib/workflows/test-workflow.ts
import { sleep } from "workflow"

async function stepOne(input: string) {
  "use step"
  return `step-one processed: ${input}`
}

async function stepTwo(value: string) {
  "use step"
  return `step-two processed: ${value}`
}

export async function testWorkflow(input: string) {
  "use workflow"
  const result1 = await stepOne(input)
  await sleep(1000)
  const result2 = await stepTwo(result1)
  return { input, result1, result2 }

Runtime diagnostic endpoint output

{
  "nodeVersion": "v25.8.1",
  "turbopack": true,
  "workflowApiExports": ["Run", "getHookByToken", "getRun", "resumeHook", "resumeWebhook", "runStep", "start"],
  "startType": "function",
  "testWorkflowType": "function",
  "testWorkflowName": "s",
  "testWorkflowKeys": [],
  "testWorkflowString": "async function s(e){let s=await t(e);await (0,r.sleep)(1e3);let n=await o(s);return{input:e,result1:s,result2:n}}",
  "status": "FAILED",
  "error": "'start' received an invalid workflow function...",
  "workflowDataExists": false
}

Analysis

• testWorkflowName: "s" — function was minified, not transformed into a workflow stub
• testWorkflowKeys: [] — no workflow metadata attached
• workflowDataExists: false — .workflow-data/ directory never created during next build
• The "use workflow" directive was stripped by the minifier but never processed by the WDK SWC transform

The WDK routes DO get generated in .next/server/app/.well-known/workflow/ and the world chunk exists (@workflow_world_dist_index), but the directive transform that should convert annotated functions into manifest-referenced stubs is not executing.

Environment: workflow@4.2.0-beta.71, next@16.1.5, Turbopack (default), Node 25.8.1

[pranaygp]

@jonio87 could you (or your agent) please share an example repo where you're seeing this? We run the same thing in our e2e tests and I'm not able to reproduce your issue myself. It sounds to me like there's something else in your setup that's causing the build toolchain to not work correctly (this error means the workflow loader isn't running correctly) so a full test repo I can use to reproduce this would be really helpful