vercel/ai · error

Sandbox session is not available

Error message

Sandbox session is not available

What it means

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.

Source

Thrown at packages/anthropic/src/tool/bash_20241022.ts:87

export function bash_20241022<OUTPUT>(
  options: Omit<Bash20241022Options<OUTPUT>, 'execute'> & {
    execute: Bash20241022Options<OUTPUT>['execute'];
  },
): ProviderDefinedTool<Bash20241022Input, OUTPUT, {}>;
export function bash_20241022<OUTPUT>(
  options: Bash20241022OptionsWithNullableExecute<OUTPUT> = {},
): ProviderDefinedTool<Bash20241022Input, OUTPUT, {}> {
  const { execute, ...rest } = options;

  if (execute === undefined) {
    return bash_20241022_internal({
      ...rest,
      execute: async (
        { command },
        { abortSignal, experimental_sandbox: sandbox },
      ) => {
        if (!sandbox) {
          throw new Error('Sandbox session is not available');
        }

        return await sandbox.run({
          command,
          abortSignal,
        });
      },
    } as Bash20241022Options<Bash20241022DefaultOutput>) as ReturnType<
      typeof bash_20241022_internal<OUTPUT>
    >;
  }

  return bash_20241022_internal({
    ...rest,
    ...(execute === null ? {} : { execute }),
  } as Bash20241022Options<OUTPUT>);
}

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Provide an `experimental_sandbox` session in the tool execution options so bash commands can run.
2. 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.
3. Verify the sandbox is created and connected before the model starts invoking tools.

Example fix

// before
tools: { bash: bashTool() } // no sandbox supplied
// after
tools: {
  bash: bashTool({
    execute: async ({ command }, opts) => {
      const sandbox = await getSandbox(); // provide experimental_sandbox in options
      return sandbox.run({ command, abortSignal: opts.abortSignal });
    },
  }),
}

if (!sandboxSession) {
  throw new Error('bash_20241022 tool requires an experimental_sandbox session');
}
// pass it via tool execution options before enabling the bash tool

function hasSandbox(opts: any): opts is { experimental_sandbox: { run: (args: { command: string }) => Promise<unknown> } } {
  return !!opts?.experimental_sandbox && typeof opts.experimental_sandbox.run === 'function';
}

try {
  return await sandbox.run({ command, abortSignal });
} catch (error) {
  if (error instanceof Error && error.message === 'Sandbox session is not available') {
    return { type: 'error', error: 'Bash tool requires a sandbox session; initialize one before running the agent.' };
  }
  throw error;
}

When it happens

Trigger: Enabling the anthropic bash_20241022 tool (via bashTool) in generateText/streamText without providing experimental_sandbox in the tool execution options / agent context.

Common situations: 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.

Related errors

• Sandbox session is not available
• Invalid argument for parameter batch: batch must be a suppor
• error.message
• CODE_MODE_HOST_TOOL_ERROR
• CODE_MODE_TOOL_ERROR

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/a7ffbf606e6a49a0. Report an issue: GitHub.