{"record":{"id":"a7ffbf606e6a49a0","repo":"vercel/ai","slug":"sandbox-session-is-not-available","errorCode":null,"errorMessage":"Sandbox session is not available","messagePattern":"Sandbox session is not available","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/anthropic/src/tool/bash_20241022.ts","lineNumber":87,"sourceCode":"export function bash_20241022<OUTPUT>(\n  options: Omit<Bash20241022Options<OUTPUT>, 'execute'> & {\n    execute: Bash20241022Options<OUTPUT>['execute'];\n  },\n): ProviderDefinedTool<Bash20241022Input, OUTPUT, {}>;\nexport function bash_20241022<OUTPUT>(\n  options: Bash20241022OptionsWithNullableExecute<OUTPUT> = {},\n): ProviderDefinedTool<Bash20241022Input, OUTPUT, {}> {\n  const { execute, ...rest } = options;\n\n  if (execute === undefined) {\n    return bash_20241022_internal({\n      ...rest,\n      execute: async (\n        { command },\n        { abortSignal, experimental_sandbox: sandbox },\n      ) => {\n        if (!sandbox) {\n          throw new Error('Sandbox session is not available');\n        }\n\n        return await sandbox.run({\n          command,\n          abortSignal,\n        });\n      },\n    } as Bash20241022Options<Bash20241022DefaultOutput>) as ReturnType<\n      typeof bash_20241022_internal<OUTPUT>\n    >;\n  }\n\n  return bash_20241022_internal({\n    ...rest,\n    ...(execute === null ? {} : { execute }),\n  } as Bash20241022Options<OUTPUT>);\n}\n","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/anthropic/src/tool/bash_20241022.ts#L69-L105","documentation":"The bash_20241022 tool's execute function requires an `experimental_sandbox` session supplied via the tool-call options. When a model invokes the bash tool and no sandbox session is present in the options, the execute callback throws this plain Error. The tool can only run commands inside a provided sandbox.","triggerScenarios":"Enabling the anthropic bash_20241022 tool (via bashTool) in generateText/streamText without providing experimental_sandbox in the tool execution options / agent context.","commonSituations":"Using the bash tool in environments where sandboxing isn't wired up (serverless, plain scripts); forgetting to pass a sandbox (e.g. from @ai-sdk/sandbox or a custom session) when configuring agentic tool loops.","solutions":["Provide an `experimental_sandbox` session in the tool execution options so bash commands can run.","If sandboxing is not available in your environment, remove the bash tool from the toolset and use a custom execute that runs commands with explicit controls.","Verify the sandbox is created and connected before the model starts invoking tools."],"exampleFix":"// before\ntools: { bash: bashTool() } // no sandbox supplied\n// after\ntools: {\n  bash: bashTool({\n    execute: async ({ command }, opts) => {\n      const sandbox = await getSandbox(); // provide experimental_sandbox in options\n      return sandbox.run({ command, abortSignal: opts.abortSignal });\n    },\n  }),\n}","handlingStrategy":"validation","validationCode":"if (!sandboxSession) {\n  throw new Error('bash_20241022 tool requires an experimental_sandbox session');\n}\n// pass it via tool execution options before enabling the bash tool","typeGuard":"function hasSandbox(opts: any): opts is { experimental_sandbox: { run: (args: { command: string }) => Promise<unknown> } } {\n  return !!opts?.experimental_sandbox && typeof opts.experimental_sandbox.run === 'function';\n}","tryCatchPattern":"try {\n  return await sandbox.run({ command, abortSignal });\n} catch (error) {\n  if (error instanceof Error && error.message === 'Sandbox session is not available') {\n    return { type: 'error', error: 'Bash tool requires a sandbox session; initialize one before running the agent.' };\n  }\n  throw error;\n}","preventionTips":["Always create and inject a sandbox session when enabling Anthropic bash tools.","Skip bash tool registration in environments where sandboxing is unavailable.","Cover the agent tool loop with an integration test that exercises the bash tool."],"tags":["tooling","sandbox","missing-dependency"],"backgroundTag":"missing-sandbox-session","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}