{"record":{"id":"093ec98415b448a0","repo":"mastra-ai/mastra","slug":"execa-is-not-available-in-cloudflare-workers","errorCode":null,"errorMessage":"execa is not available in Cloudflare Workers","messagePattern":"execa is not available in Cloudflare Workers","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/cloudflare/src/index.ts","lineNumber":148,"sourceCode":"export const parseJsonConfigFileContent = () => ({ errors: [new Error('TypeScript not available')], fileNames: [], options: {} });\nexport const flattenDiagnosticMessageText = (message) => typeof message === 'string' ? message : message?.messageText || '';\nexport const ScriptTarget = { Latest: 99 };\nexport const ModuleKind = { ESNext: 99 };\nexport const JsxEmit = { ReactJSX: 4 };\nexport const DiagnosticCategory = { Warning: 0, Error: 1, Suggestion: 2, Message: 3 };\nexport const sys = {\n  fileExists: () => false,\n  readFile: () => undefined,\n};\n`;\n\n    await writeFile(join(outputDirectory, this.outputDir, typescriptStubPath), typescriptStub);\n\n    // Write execa stub — execa is used by @mastra/core's local sandbox process manager\n    // but is not available/needed in Cloudflare Workers\n    const execaStubPath = 'execa-stub.mjs';\n    const execaStub = `// Stub for execa - not available at runtime in Cloudflare Workers\nexport const execa = () => { throw new Error('execa is not available in Cloudflare Workers'); };\nexport const execaNode = execa;\nexport const execaSync = execa;\nexport const execaCommand = execa;\nexport const execaCommandSync = execa;\nexport const $ = execa;\n`;\n    await writeFile(join(outputDirectory, this.outputDir, execaStubPath), execaStub);\n\n    // Write readable-stream stub — redirects to native node:stream available via nodejs_compat.\n    // readable-stream is a userland copy of Node.js streams used by packages like elevenlabs.\n    // Bundling it for Workers pulls in Node.js polyfills (abort-controller, process/, string_decoder/)\n    // that are unnecessary and fail to resolve. The native node:stream is API-compatible.\n    const readableStreamStubPath = 'readable-stream-stub.mjs';\n    const readableStreamStub = `// Redirect readable-stream to native node:stream (available via nodejs_compat)\nimport stream from 'node:stream';\nexport const { Readable, Writable, Duplex, Transform, PassThrough, Stream, pipeline, finished } = stream;\nexport default stream;\n`;","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/cloudflare/src/index.ts#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Disable features that require local subprocesses when targeting Cloudflare Workers","Use a Workers-compatible code-mode/execution transport (e.g. remote sandbox or Cloudflare-native option)","Guard the offending feature behind runtime detection and fall back to Workers-safe behavior","If you need process spawning, deploy to a Node runtime (Cloudflare Containers/Node server) instead"],"exampleFix":"// before\nconst sandbox = new LocalSandbox(); // spawns processes -> stub throws in Workers\n// after\nif (runtime === 'workers') {\n  useRemoteExecution();\n} else {\n  const sandbox = new LocalSandbox();\n}","handlingStrategy":"fallback","validationCode":"const isWorkers = typeof WebSocketPair !== 'undefined' || (globalThis as any).caches?.default !== undefined;\nif (isWorkers && needsLocalSandbox) throw new Error('Local sandbox features are not supported on Cloudflare Workers');","typeGuard":"function runsInCloudflareWorkers(): boolean {\n  return typeof (globalThis as any).WebSocketPair !== 'undefined';\n}","tryCatchPattern":"try {\n  await sandbox.run(code);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('execa is not available in Cloudflare Workers')) {\n    return useRemoteExecutionFallback(code);\n  } else throw err;\n}","preventionTips":["Audit tools/features for subprocess usage before targeting Workers","Use Workers-compatible execution transports (remote sandboxes) in CF deploys","Add a runtime capability check before invoking sandbox/process-manager code paths","Deploy subprocess-dependent features to Node runtimes instead"],"tags":["cloudflare","workers","runtime","sandbox","subprocess"],"backgroundTag":"unsupported-runtime-api","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}