API Workers

Workers-specific warnings

instructions resolver runs after env injection. When instructions is a function, it runs inside initializeApp(env) — after injectEnvVars() — so env-derived text reaches the model without fighting the Workers module-load lifecycle:

export default createWorkerHandler({
  tools: [echoTool],
  instructions: (env) =>
    `Region: ${env.ENVIRONMENT ?? 'production'}.` +
    (env.MAINTENANCE_MODE ? ' Read-only mode — writes disabled.' : ''),
});

Plain strings work the same as on createApp. Type extends Omit<CreateAppOptions, 'instructions'>, so this is the only option whose shape differs between Node and Worker entry points.

Lazy env parsing is mandatory. Cloudflare injects env bindings at request time via injectEnvVars(), after all static module imports complete. Never parse process.env at module top-level in Workers:

// WRONG — parsed before env is injected
const apiKey = process.env.MY_API_KEY;  // undefined in Workers

// CORRECT — lazy parse inside a function or getter
export function getServerConfig() {
  return ServerConfigSchema.parse({ apiKey: process.env.MY_API_KEY });
}

in-memory storage is volatile. Data stored with the in-memory provider is lost between cold starts and is not shared across Worker instances. Use cloudflare-kv, cloudflare-r2, or cloudflare-d1 for any state that must persist or be shared.

Multi-round-trip retries land on any isolate. Each 2026-07-28 request builds its own McpServer, and the retry after an input_required result can be routed to a different isolate. Set MCP_REQUEST_STATE_KEY (≥ 32 bytes) as a Worker secret — it is a core binding, injected like the rest — so every isolate seals and verifies requestState with the same key, and keep a consent gate's record (api-context § Consent gates) in cloudflare-d1. in-memory loses it to the next isolate, so the retry asks again. Never cloudflare-kv: it is eventually consistent, so a retry served elsewhere may not see the record yet, and a deletion may not yet stop an immediate replay — it widens the window concurrent retries already have, since redeeming is not atomic on any provider until ctx.state gains a take (#593).

Node-only utilities throw in Workers. scheduler (node-cron), sanitizePath (fs-based), and filesystem storage provider all throw ConfigurationError when called from a Worker. Guard with runtimeCaps.isNode or avoid entirely.

DataCanvas is unavailable in Workers. DuckDB has no V8-isolate build, so core.canvas is always undefined on Workers. Setting CANVAS_PROVIDER_TYPE=duckdb (the only non-default value) in wrangler.toml triggers a fail-closed ConfigurationError at init time:

DuckDB canvas requires Node.js or Bun. Set CANVAS_PROVIDER_TYPE=none or omit it for Cloudflare Workers deployment.

Leave the env unset (or set to none) for Worker deployments. Tools that conditionally use canvas should check the module-level accessor (if (!getCanvas()) { ... }) and surface a clear "feature unavailable on this deployment" message. See api-canvas for the full DataCanvas reference and setup wiring pattern.

The default notification bus is per-isolate. core.notify and the modern era's subscriptions/listen streams share a change-event bus that defaults to in-process — which on Workers means one bus per isolate, so a background emission reaches only the listeners that happen to live in the isolate that produced it. Handler-time ctx.notify* is unaffected (the listen stream and the handler are the same request). For fan-out that must cross isolates, supply a bus of your own, backed by a Durable Object or another shared channel:

createWorkerHandler({ tools, eventBus: myDurableObjectBackedBus });

The interface is the SDK's ServerEventBus — publish(event) and subscribe(listener). See api-context's notification section for what publishes onto it.

Testing Workers with miniflare

bun run test:worker runs the worker suite under tests/config/vitest.worker.ts (using @cloudflare/vitest-pool-workers + miniflare). Each test file gets its own fresh V8 isolate — module scope (including createWorkerHandler's appPromise singleton) is reset between files.

tests/config/vitest.worker.ts miniflare bindings

Declare all storage bindings used in the suite:

cloudflareTest({
  main: './tests/fixtures/worker-runtime.fixture.ts',
  miniflare: {
    bindings: { STORAGE_PROVIDER_TYPE: 'cloudflare-kv', ... },
    kvNamespaces: ['KV_NAMESPACE', 'CUSTOM_KV'],
    r2Buckets:    ['R2_BUCKET'],
    d1Databases:  ['DB'],
  },
})

Binding names must match the hardcoded names in storageFactory.ts (KV_NAMESPACE, R2_BUCKET, DB).

Per-provider test isolation

bindings.STORAGE_PROVIDER_TYPE is a global default. Per-provider test files override it by passing a modified env to worker.fetch():

import { env } from 'cloudflare:workers';

// Fresh isolate per file — appPromise starts null.
// First fetch initialises the singleton with the overridden provider type.
const r2Env = { ...env, STORAGE_PROVIDER_TYPE: 'cloudflare-r2' };
await worker.fetch(request, r2Env, ctx);

Use reset() from cloudflare:test in afterEach to clear binding state between tests. For D1, re-apply migrations immediately after each reset() (reset wipes the schema):

import { applyD1Migrations, reset } from 'cloudflare:test';

afterEach(async () => {
  await reset();
  await applyD1Migrations(env.DB, [{ name: '0001_schema', queries: [CREATE_TABLE_SQL] }]);
});

D1 schema setup

The cloudflare-d1 provider requires the kv_store table before any operations. Apply it in beforeAll via applyD1Migrations:

const KV_STORE_MIGRATION = `
CREATE TABLE IF NOT EXISTS kv_store (
  tenant_id TEXT NOT NULL,
  key       TEXT NOT NULL,
  value     TEXT NOT NULL,
  expires_at INTEGER,
  PRIMARY KEY (tenant_id, key)
)`;

beforeAll(async () => {
  await applyD1Migrations(env.DB, [
    { name: '0001_create_kv_store', queries: [KV_STORE_MIGRATION] },
  ]);
  sessionId = await openSession(d1Env);
});

R2 list limit

The R2 provider fetches limit + 1 objects to detect further pages. Miniflare caps R2 MaxKeys at 1000, so the default limit=1000 → request 1001 → error. Pass limit: 100 (or any value ≤ 999) to ctx.state.list() in test fixtures to stay under the cap:

const result = await ctx.state.list(prefix, { limit: 100 });

Storage probe pattern

Expose storage operations as MCP tools in the fixture to test them through the real HTTP surface:

const storageSetTool = tool('storage_set', {
  input: z.object({ key: z.string().describe('...'), value: z.string().describe('...') }),
  output: z.object({ ok: z.boolean().describe('Always true on success') }),
  async handler(input, ctx) {
    await ctx.state.set(input.key, input.value);
    return { ok: true };
  },
  format: (r) => [{ type: 'text', text: `ok=${r.ok}` }],
});

Call via tools/call over MCP JSON-RPC and assert on structuredContent. See tests/worker/storage-r2.worker.test.ts and tests/worker/storage-d1.worker.test.ts for the full pattern.