getStepMetadata failing inside of step function

[nwp]

I have started to see the following error message: "Error: getStepMetadata() can only be called inside a step function". However, it IS being called within a step function and it persists in workflow 4.0.1-beta.29

[adriandlam]

hey @nwp could you share a minimum repro?

[nwp]

I had to remove all instances of getStepMetadata in order to get rid of the error.

import 'server-only';
import { getStepMetadata } from 'workflow';
import { db } from '@/lib/db';
import { message, chat } from '@/lib/db/schema';
import { eq, and, gte, desc, sql } from 'drizzle-orm';
import { generateObject } from 'ai';
import {
 trackedProvider,
 setAITrackingContext,
} from '@/lib/ai/tracked-provider';
import { dynamicGreetingSchema } from '@/lib/ai/greeting/schema';
import { greetingPrompt } from '@/lib/ai/greeting/prompt';
import { cacheGreeting } from '@/lib/ai/greeting/cache';
import type { DynamicGreeting } from '@/lib/ai/greeting/schema';
import { createRetryableError } from '@/lib/workflows/retry-utils';
import type { SerializableTenant } from '@/lib/workflows/types';
import { BACKGROUND_MODEL } from '@/lib/ai/models';

export interface GreetingContext {
 userId: string;
 tenant: SerializableTenant;
 firstName: string;
}

export async function generateGreetingWorkflow(context: GreetingContext) {
 'use workflow';

 const recentMessages = await fetchRecentMessages(context.userId);
 const greeting = await generateGreeting(context, recentMessages);
 await cacheGeneratedGreeting(context, greeting);

 return greeting;
}

async function fetchRecentMessages(
 userId: string,
): Promise<Array<{ text: string; chatTitle: string }> | null> {
 'use step';

 const metadata = await getStepMetadata();
 console.log(`Fetching recent messages (attempt ${metadata.attempt})`);

 try {
 const recentMessages = await db
 .select({
 text: sql<string>`(${message.parts}::jsonb -> 0 ->> 'text')`,
 chatTitle: chat.title,
 })
 .from(message)
 .innerJoin(chat, eq(message.chatId, chat.id))
 .where(
 and(
 eq(chat.userId, userId),
 eq(message.role, 'user'),
 gte(message.createdAt, sql`NOW() - INTERVAL '7 days'`),
 ),
 )
 .orderBy(desc(message.createdAt))
 .limit(5);

 return recentMessages.length > 0 ? recentMessages : null;
 } catch (error) {
 const message = error instanceof Error ? error.message : 'Unknown error';
 console.error(`Failed to fetch recent messages (attempt ${metadata.attempt}):`, message);
 throw createRetryableError(`Failed to fetch recent messages: ${message}`, metadata.attempt);
 }
}

async function generateGreeting(
 context: GreetingContext,
 recentMessages: Array<{ text: string; chatTitle: string }> | null,
): Promise<DynamicGreeting> {
 'use step';

 const metadata = await getStepMetadata();
 console.log(`Generating greeting (attempt ${metadata.attempt})`);

 try {
 setAITrackingContext({
 userId: context.userId,
 conversationId: 'greeting-workflow',
 tenantName: context.tenant.name,
 subdomain: context.tenant.slug,
 phase: 'greeting',
 traceName: 'greeting-workflow-generation',
 });

 const prompt = greetingPrompt(context.firstName, recentMessages);

 const timeoutPromise = new Promise<never>((_, reject) =>
 setTimeout(() => reject(new Error('Generation timeout')), 90000),
 );

 const result = await Promise.race([
 generateObject({
 model: trackedProvider.languageModel(BACKGROUND_MODEL),
 schema: dynamicGreetingSchema,
 prompt,
 output: 'object',
 schemaName: 'DynamicGreeting',
 schemaDescription: 'A personalized greeting with exactly 2 suggestion prompts',
 }),
 timeoutPromise,
 ]);

 return dynamicGreetingSchema.parse(result.object);
 } catch (error) {
 const message = error instanceof Error ? error.message : 'Unknown error';
 console.error(`Greeting generation failed (attempt ${metadata.attempt}):`, message);
 throw createRetryableError(`Failed to generate greeting: ${message}`, metadata.attempt);
 }
}

async function cacheGeneratedGreeting(
 context: GreetingContext,
 greeting: DynamicGreeting,
) {
 'use step';

 try {
 await cacheGreeting(context.tenant.id, context.userId, greeting);
 } catch (error) {
 console.error('Failed to cache greeting:', error);
 }
}

[adriandlam]

i tried reproducing using your exact code (with stubbed external dependencies) but i wasn't able to. Could you try bumping to 4.0.1-beta.32 and see if that helps? Also happy to take a look at your project to see what's happening

[Benjamin-Lee]

I was able to reproduce on 4.1.0-beta.60. In my case, this is only happening locally and my failing step is in a directly awaited (flattened) workflow. No issue when the composed workflow is called directly.

[Benjamin-Lee]

Claude was able to get this bug fixed locally. Posting it here since the plugin it made successfully resolved the issue.

---

Dug into the root cause on 4.1.0-beta.60 with Vite 7 + Nitro. The issue is a dual module instance problem with AsyncLocalStorage in dev mode.

Root cause

The workflow build tool emits steps.mjs with two different import styles:

// bare specifier — Vite SSR externalises this → loaded natively ✅
import { registerStepFunction } from "workflow/internal/private";

// relative path — Vite SSR does NOT externalise this → loaded through Vite SSR pipeline ❌
import { getStepMetadata } from "../../../../../node_modules/.bun/@workflow+core@4.1.0-beta.60+.../dist/step/get-step-metadata.js";

Vite SSR only externalises bare-specifier imports (i.e. node_modules packages). The relative-path import of get-step-metadata.js goes through Vite SSR's module pipeline, which creates a separate module instance of context-storage.js — and therefore a separate AsyncLocalStorage — from the one the step handler uses (loaded natively via the bare-specifier chain).

So when the step handler calls contextStorage.run(ctx, () => stepFn(args)), it sets context on instance A. But when the step function calls getStepMetadata() → contextStorage.getStore(), it reads from instance B. Store is empty → error.

This explains why registerStepFunction/getStepFunction work fine (they use the bare specifier "workflow/internal/private" → shared native module → shared Map), while getStepMetadata breaks.

This only affects dev mode (Vite SSR). In production, Nitro's Rollup build bundles everything into a single output file, so there's only one copy of context-storage.js and one AsyncLocalStorage instance. The dual-instance problem is specific to Vite SSR's per-module loading, where bare specifiers and relative paths are externalised differently.

Workaround

A Vite plugin that intercepts the SSR load of get-step-metadata.js and redirects it to the bare specifier "workflow", which Vite SSR externalises:

import type { Plugin } from "vite"

function workflowStepMetadataNativeProxy(): Plugin {
 return {
 name: "workflow-step-metadata-native-proxy",
 enforce: "pre",
 load(id, options) {
 if (!options?.ssr) return null
 if (
 id.includes("get-step-metadata") &&
 (id.includes("@workflow/core") || id.includes("@workflow+core"))
 ) {
 return `export { getStepMetadata } from "workflow";`
 }
 return null
 },
 }
}

Add workflowStepMetadataNativeProxy() as the first plugin in your Vite config.

Suggested fix in the SDK

The workflow build tool should emit getStepMetadata (and any other @workflow/core step utilities) as bare-specifier imports in steps.mjs, the same way it already does for registerStepFunction. That would make Vite SSR externalise them consistently and avoid the dual-instance problem.