Troubleshooting (FAQ)

Note: The abx commands shown on this page are provided by the Node.js CLI in the cli repository (npm install -g @agent-sandbox/cli). CLI-specific documentation (CLI design, tutorial, reference) lives there too; this repository documents the Python SDK (agent-sandbox) and the container-side runtime (agent-sandbox-server).

Connection Timeout

Symptoms

[E5001] Failed to connect to sandbox service
  Suggestion: Check network connectivity and firewall rules.

Troubleshooting

1. Check network: Confirm you can access api.cn-hangzhou.e2b.fc.aliyuncs.com bash curl -I https://api.cn-hangzhou.e2b.fc.aliyuncs.com

2. Check timeout configuration: Increase the HTTP timeout bash abx config set http_timeout 60

3. Check proxy: If behind a proxy, ensure https_proxy is configured correctly

4. Check region: Confirm the region setting is correct bash abx config get region

Authentication Failure

E1001 — Invalid or Missing API Key

[E1001] API key cannot be empty
  Suggestion: Check your ABX_SANDBOX_API_KEY environment variable or pass sandbox_api_key.

Solution:

# Check configuration status
abx config get sandbox_api_key

# Re-set API Key
abx config set sandbox_api_key your-api-key

# Or set the environment variable
export ABX_SANDBOX_API_KEY="your-api-key"

E1003 — Invalid AK/SK Credentials

[E1003] AccessKey ID and Secret cannot be empty

Solution: Ensure both AK ID and AK Secret are set:

export ALICLOUD_ACCESS_KEY_ID="your-ak-id"
export ALICLOUD_ACCESS_KEY_SECRET="your-ak-secret"

E1002 — Token Expired

[E1002] The SDK should auto-refresh tokens. If this persists, check system clock synchronization.

Solution: Check that the system clock is accurate. The SDK auto-refreshes AK/SK temporary tokens (valid for 3600 seconds, refreshed 300 seconds before expiry).

Template Not Found

E2001 — TemplateNotFoundError

[E2001] Template 'my-template' not found
  Suggestion: Run 'abx template list' to see available templates.

Solution:

1. Check the template name for typos
2. Confirm the template is installed: bash abx template install owner/repo
3. Test with the default template: bash abx create --template base

E2009 — SandboxNotFoundError

[E2009] Sandbox 'sbx-xxxx' was not found.

The platform answered HTTP 404 to Sandbox.connect(), get_info(), set_timeout(), pause() or resume() for that ID.

Solution: Check the ID for typos and run abx list to see the running sandboxes. A killed or expired sandbox cannot be reconnected; create a new one. kill() of an unknown ID stays idempotent and does not raise.

Capability Not Supported (E3004)

Symptoms

[E3004] Capability 'ports' is not supported by this sandbox template.
  Suggestion: Declare 'ports' in the template's capabilities list (template.yaml) or use a template that supports it.

Explanation

Agent Sandbox uses a capability model to control sandbox features. Each capability must be explicitly declared in the template:

Solution

If you need the terminal or ports capability, use a template that declares it, or create a custom template:

# template.yaml
name: my-web-template
capabilities:
  - shell
  - files
  - code
  - terminal
  - ports

Server-side capability groups note: The server has 8 capability groups. TERMINAL is enabled by default; only DEV_TOOLS and BROWSER are disabled by default (_DEFAULT_DISABLED = {DEV_TOOLS, BROWSER}). Client-side capabilities (the capabilities field) and server-side capability groups are controls at different levels.

Quota Exceeded

E2002 — QuotaExceededError

[E2002] Sandbox quota has been exceeded
  Suggestion: Destroy idle sandboxes or request a quota increase.

Solution:

# View running sandboxes
abx list --status running

# Destroy unneeded sandboxes
abx kill sbx-xxxx

# Batch destroy
abx kill --all --yes

Command Execution Timeout

E3001 — CommandTimeoutError

[E3001] Command execution timed out
  Suggestion: Increase the timeout parameter or check if the command is hanging.

Solution:

# Increase timeout in SDK
result = await sandbox.commands.run("long-command", timeout=300)

# Increase timeout in CLI
abx exec sbx-xxxx "long-command" --timeout 300

Build and Deploy Issues

Build, push and deploy errors (the E7xxx codes, a missing LLM key for abx create / abx template init) are raised by the abx CLI, not by this SDK. See the CLI troubleshooting guide and Build and deploy.

File Operations

E4001 — File Not Found

# Check if the file exists first
exists = await sandbox.files.exists("/path/to/file")
if not exists:
    print("File does not exist")

# List directory contents
entries = await sandbox.files.list("/home/user")

E4002 — Permission Denied

Check file permissions. The default user in the sandbox is user; you can specify the user parameter in commands.

Installation Issues

pip install Fails

# Ensure the correct package name
pip install agent-sandbox

# If dependency conflicts occur
pip install agent-sandbox --force-reinstall

Python SDK Not Found

Confirm that Python's bin directory is in your PATH:

python -m agent_sandbox --version
# Or
pip show agent-sandbox | grep Location

Next Steps

• Authentication — Authentication configuration
• Configuration Reference — All configuration options
• Error Codes Reference — Complete error code list

Related: the abx CLI

CLI-specific problems (abx not found, abx deploy with no Dockerfile, long deploy steps, invalid shortcut targets, abx template init --adopt confirmations) are covered in the CLI repository: Troubleshooting (CLI).