{"record":{"id":"87365e04105a0ba9","repo":"mastra-ai/mastra","slug":"sandbox-provider-sandbox-provider-does-not-su-87365e","errorCode":null,"errorMessage":"Sandbox provider '${sandbox.provider}' does not support executeCommand, which is required to run git and filesystem operations in a session.","messagePattern":"Sandbox provider '(.+?)' does not support executeCommand, which is required to run git and filesystem operations in a session\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"mastracode/factory/src/sandbox/materialization.ts","lineNumber":40,"sourceCode":"   * these helpers read: core's `CommandResult` also carries `success` and\n   * `executionTimeMs`, and asking for them would reject test doubles that\n   * report exactly what the helpers consume.\n   */\n  executeCommand(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<SandboxCommandResult>;\n};\n\n/**\n * Narrow a sandbox to one that can run commands, or fail saying which\n * capability is missing.\n *\n * Callers hold a `WorkspaceSandbox`, whose `executeCommand` is optional.\n * Optional-chaining past it would hand every caller `undefined` where it\n * expects an exit code, turning a misconfigured provider into a git command\n * that silently did nothing.\n */\nexport function requireExec(sandbox: WorkspaceSandbox): ExecutableSandbox {\n  if (typeof sandbox.executeCommand !== 'function') {\n    throw new Error(\n      `Sandbox provider '${sandbox.provider}' does not support executeCommand, which is required to run git and filesystem operations in a session.`,\n    );\n  }\n  return sandbox as ExecutableSandbox;\n}\n","sourceCodeStart":22,"sourceCodeEnd":46,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/sandbox/materialization.ts#L22-L46","documentation":"requireExec narrows a WorkspaceSandbox to an ExecutableSandbox by checking that executeCommand is a function. If the configured sandbox provider lacks executeCommand, materialization throws immediately rather than letting git/filesystem operations silently no-op with an undefined exit code, since session setup and teardown depend on running real commands.","triggerScenarios":"Calling requireExec (directly or via #teardownSessionSandbox during session teardown) with a sandbox whose provider is read-only or non-executing — e.g. a provider configured with an exec-disabled or command-less mode, or passing a custom WorkspaceSandbox implementation that never defined executeCommand.","commonSituations":"Configuring a storage/preview-only sandbox provider where an executing one (docker/VM/shell) is required; a custom provider implementing only the file-transfer surface; a version change where executeCommand was renamed or made optional on the interface.","solutions":["Configure a sandbox provider that implements executeCommand (an executing provider such as a container/VM/local shell).","If using a custom provider, implement executeCommand(command) returning { stdout, stderr, exitCode }.","Check the provider name in your factory/sandbox config for typos that fall back to a non-executing default.","Upgrade/downgrade so the provider matches the WorkspaceSandbox interface expected by this version."],"exampleFix":"// before\nsandbox: { provider: 'readonly-fs' } // no executeCommand\n// after\nsandbox: { provider: 'docker', image: 'workspace:latest' } // provider with executeCommand support","handlingStrategy":"type-guard","validationCode":"function assertExecutable(sandbox) {\n  if (typeof sandbox.executeCommand !== 'function') {\n    throw new Error(`Provider '${sandbox.provider}' cannot run sessions; choose an executing provider.`);\n  }\n}\nassertExecutable(configuredSandbox); // before session create/teardown","typeGuard":"interface ExecutableSandbox { executeCommand(cmd: string): Promise<{ stdout: string; stderr: string; exitCode: number }> }\nfunction isExecutableSandbox(s: WorkspaceSandbox): s is WorkspaceSandbox & ExecutableSandbox {\n  return typeof (s as Partial<ExecutableSandbox>).executeCommand === 'function';\n}","tryCatchPattern":"try {\n  await teardownSessionSandbox(session);\n} catch (e) {\n  if (/does not support executeCommand/.test(e.message)) {\n    logger.error('Misconfigured sandbox provider; skipping command-based teardown', { provider: session.sandbox.provider });\n    return; // or re-create session with an executing provider\n  }\n  throw e;\n}","preventionTips":["Verify the provider supports executeCommand at config-load time, not at session teardown.","Prefer built-in executing providers (container/VM/local shell) over storage-only modes for sessions.","For custom providers, run a smoke `pwd` command right after construction."],"tags":["sandbox","configuration","missing-capability"],"backgroundTag":"sandbox-provider-missing-execute","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}