mastra-ai/mastra · error

execa is not available in Cloudflare Workers

Error message

execa is not available in Cloudflare Workers

What it means

The Cloudflare deployer writes an execa stub module into the output bundle because @mastra/core's local sandbox process manager imports execa, which cannot work in Cloudflare Workers (no subprocess APIs). Any code path that actually calls the stubbed execa functions throws 'execa is not available in Cloudflare Workers' at runtime.

Source

Thrown at deployers/cloudflare/src/index.ts:148

export const parseJsonConfigFileContent = () => ({ errors: [new Error('TypeScript not available')], fileNames: [], options: {} });
export const flattenDiagnosticMessageText = (message) => typeof message === 'string' ? message : message?.messageText || '';
export const ScriptTarget = { Latest: 99 };
export const ModuleKind = { ESNext: 99 };
export const JsxEmit = { ReactJSX: 4 };
export const DiagnosticCategory = { Warning: 0, Error: 1, Suggestion: 2, Message: 3 };
export const sys = {
  fileExists: () => false,
  readFile: () => undefined,
};
`;

    await writeFile(join(outputDirectory, this.outputDir, typescriptStubPath), typescriptStub);

    // Write execa stub — execa is used by @mastra/core's local sandbox process manager
    // but is not available/needed in Cloudflare Workers
    const execaStubPath = 'execa-stub.mjs';
    const execaStub = `// Stub for execa - not available at runtime in Cloudflare Workers
export const execa = () => { throw new Error('execa is not available in Cloudflare Workers'); };
export const execaNode = execa;
export const execaSync = execa;
export const execaCommand = execa;
export const execaCommandSync = execa;
export const $ = execa;
`;
    await writeFile(join(outputDirectory, this.outputDir, execaStubPath), execaStub);

    // Write readable-stream stub — redirects to native node:stream available via nodejs_compat.
    // readable-stream is a userland copy of Node.js streams used by packages like elevenlabs.
    // Bundling it for Workers pulls in Node.js polyfills (abort-controller, process/, string_decoder/)
    // that are unnecessary and fail to resolve. The native node:stream is API-compatible.
    const readableStreamStubPath = 'readable-stream-stub.mjs';
    const readableStreamStub = `// Redirect readable-stream to native node:stream (available via nodejs_compat)
import stream from 'node:stream';
export const { Readable, Writable, Duplex, Transform, PassThrough, Stream, pipeline, finished } = stream;
export default stream;
`;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Disable features that require local subprocesses when targeting Cloudflare Workers
2. Use a Workers-compatible code-mode/execution transport (e.g. remote sandbox or Cloudflare-native option)
3. Guard the offending feature behind runtime detection and fall back to Workers-safe behavior
4. If you need process spawning, deploy to a Node runtime (Cloudflare Containers/Node server) instead

Example fix

// before
const sandbox = new LocalSandbox(); // spawns processes -> stub throws in Workers
// after
if (runtime === 'workers') {
  useRemoteExecution();
} else {
  const sandbox = new LocalSandbox();
}

const isWorkers = typeof WebSocketPair !== 'undefined' || (globalThis as any).caches?.default !== undefined;
if (isWorkers && needsLocalSandbox) throw new Error('Local sandbox features are not supported on Cloudflare Workers');

function runsInCloudflareWorkers(): boolean {
  return typeof (globalThis as any).WebSocketPair !== 'undefined';
}

try {
  await sandbox.run(code);
} catch (err) {
  if (err instanceof Error && err.message.includes('execa is not available in Cloudflare Workers')) {
    return useRemoteExecutionFallback(code);
  } else throw err;
}

When it happens

Trigger: Running deployed Worker code that reaches @mastra/core's local sandbox/process-manager functionality (e.g. code-mode local sandbox, tool processes) — the stub's `execa`, `execaNode`, `execaCommand`, `$`, etc. are all invoked.

Common situations: Enabling a tool/feature that spawns local processes (sandboxed code execution, dev servers) in a Cloudflare-deployed app; assuming feature parity between Node deploys and Workers deploys.

Related errors

• require(${specifier}) is not available in Cloudflare Workers
• Response body is null
• Response body is null
• NODE_FAIL_INSTALL_SPECIFIED_VERSION
• FAIL_INSTALL_DEPS

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/093ec98415b448a0. Report an issue: GitHub.