{"record":{"id":"b9b9129fb554e4e5","repo":"mastra-ai/mastra","slug":"process-failed-to-spawn","errorCode":null,"errorMessage":"Process failed to spawn","messagePattern":"Process failed to spawn","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/core/src/workspace/sandbox/local-process-manager.ts","lineNumber":278,"sourceCode":"      // Non-isolated: use shell mode so the host shell interprets the command string\n      // (pipes, redirects, chaining, etc.). Isolated (seatbelt/bwrap): the wrapper\n      // already includes `sh -c` inside the sandbox, so we spawn the wrapper directly.\n      execaOptions = {\n        ...baseOptions,\n        detached: true,\n        shell: this.sandbox.isolation === 'none',\n      };\n    }\n\n    const execa = await getExeca();\n    const subprocess = execa(wrapped.command, wrapped.args, execaOptions);\n\n    // execa sets pid synchronously when the process spawns successfully.\n    // If pid is undefined, the spawn failed (bad cwd, missing command, etc.).\n    // Await the subprocess to get execa's detailed error message.\n    if (!subprocess.pid) {\n      const result = await subprocess;\n      throw new Error(result.message || 'Process failed to spawn');\n    }\n\n    const handle = new LocalProcessHandle(subprocess, subprocess.pid, Date.now(), options);\n    this._tracked.set(handle.pid, handle);\n    return handle;\n  }\n\n  async list(): Promise<ProcessInfo[]> {\n    return Array.from(this._tracked.values()).map(handle => ({\n      pid: handle.pid,\n      running: handle.exitCode === undefined,\n      exitCode: handle.exitCode,\n    }));\n  }\n}\n","sourceCodeStart":260,"sourceCodeEnd":294,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/sandbox/local-process-manager.ts#L260-L294","documentation":"LocalProcessManager.spawn() throws when execa could not start the process — `subprocess.pid` is undefined because the spawn failed synchronously (bad cwd, missing executable, permission issues). The manager awaits the subprocess promise to pull execa's detailed error message and throws that, or a generic fallback.","triggerScenarios":"Calling `spawn()` with a command that doesn't exist on PATH, a `cwd` directory that doesn't exist, or a binary without execute permission. Any case where the child fails to start so execa never assigns a pid.","commonSituations":"Typo'd or platform-specific command names (e.g. `dir` on unix); missing system dependencies in sandbox/container images; relative cwd paths that don't resolve; trying to run node_modules/.bin tools before install.","solutions":["Read `result.message` / catch the error to see execa's detailed reason (ENOENT, EACCES, etc.)","Verify the command exists: `which <cmd>` or use an absolute path to the binary","Ensure `cwd` exists and is accessible before spawning","Check execute permissions on the target binary (chmod +x)"],"exampleFix":"// before\nconst handle = await manager.spawn({ cmd: 'mytool' });\n// after\nconst bin = path.join(projectRoot, 'node_modules/.bin/mytool');\nif (!fs.existsSync(bin)) throw new Error(`mytool not installed at ${bin}`);\nconst handle = await manager.spawn({ cmd: bin, options: { cwd: projectRoot } });","handlingStrategy":"try-catch","validationCode":"import fs from 'fs';\nfunction assertSpawnable(cmd: string, cwd?: string) {\n  if (cwd && !fs.existsSync(cwd)) throw new Error(`cwd does not exist: ${cwd}`);\n  if (cmd.includes('/')) fs.accessSync(cmd, fs.constants.X_OK);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const handle = await manager.spawn({ cmd, options: { cwd } });\n} catch (err) {\n  if (/failed to spawn|ENOENT|EACCES/.test(String(err?.message))) {\n    throw new Error(`Cannot start '${cmd}' in '${cwd}': ${err.message}. Check the binary exists and is executable.`);\n  }\n  throw err;\n}","preventionTips":["Use absolute binary paths (e.g. node_modules/.bin/*) instead of relying on PATH","Verify cwd exists before spawning; resolve relative paths against a known root","Include the failing command and cwd in your own error messages for debuggability"],"tags":["process","spawn","execa","sandbox"],"backgroundTag":"spawn-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}