# FAQ and Troubleshooting

<subtitle>Scenario-organized troubleshooting checklist: Authentication, build stuck, command timeout, network access, and rate limiting.</subtitle>

---

## Quick Self-Check Checklist

When encountering issues, please troubleshoot in the following order:

1. **Are environment variables correct**: Native SDK uses `AGENTBOX_API_KEY`, E2B compatibility mode uses `E2B_API_KEY` + `E2B_DOMAIN`
2. **Does template exist**: Check if template alias is correct and if build succeeded
3. **Does network policy allow**: Sandboxes can access external network by default, but may be explicitly disabled
4. **Is rate limiting triggered**: Check request frequency and concurrency
5. **Is ready command satisfied**: Most common cause of build stuck

---

## Authentication and Permission Issues

### Symptoms
- Requests return 401 / 403 errors
- SDK indicates API Key is invalid or missing

### Troubleshooting Steps

```bash
# Check if environment variables are set
echo $AGENTBOX_API_KEY

# For E2B compatibility mode
echo $E2B_API_KEY
echo $E2B_DOMAIN
```

### Common Causes
- Incorrect environment variable names (native vs E2B)
- Variables not correctly passed in CI/containers/subprocesses
- API Key has expired or been disabled

>
> For details, see: [Prerequisites and Authentication](/docs/agent-sandbox/product/01-prerequisites)

---

## Template Build Stuck

### Symptoms
- Build stays in `building` state for a long time
- Logs continuously output same readiness check results

### Troubleshooting Steps

1. **Check ready command exit code logic**

Ready command only enters snapshot generation phase when exit code `0` is returned:

```python
# Wrong example: Service not started but returns 0
.set_start_cmd("npm start", wait_for_timeout(1000))  # 1 second too short

# Correct example: Wait for port ready
.set_start_cmd("npm start", wait_for_port(3000))
```

2. **View build logs**

```python
from ucloud_sandbox import Template, default_build_logger

Template.build(
    template,
    alias="my-template",
    on_build_logs=default_build_logger(min_level="debug")  # Enable debug level
)
```

3. **Check if start command runs normally**

Ensure the start command itself does not exit immediately or error.

>
> For details, see: [Start and Ready Commands](/docs/agent-sandbox/template/08-start-and-ready-commands)

---

## Command Execution Timeout or No Output

### Symptoms
- `commands.run()` runs too long
- Streaming output not returned or interrupted

### Troubleshooting Steps

1. **Use minimal command to verify connectivity**

```python
# Test with simple command first
result = sandbox.commands.run("echo hello")
print(result.stdout)  # Should output hello
```

2. **Change long tasks to background execution**

```python
# Run in background
process = sandbox.commands.run("long_running_task", background=True)

# Poll output
for stdout, stderr, _ in process:
    if stdout:
        print(stdout)
```

3. **Check if command itself is stuck**

Manually test the command in the sandbox to confirm it's not a command issue.

>
> For details, see: [Command Execution Overview](/docs/agent-sandbox/sdk/commands/01-overview), [Run Commands in Background](/docs/agent-sandbox/sdk/commands/03-run-commands-in-background)

---

## Network/External Network Access Failure

### Symptoms
- `curl`, `pip install`, `npm install` cannot access external network
- DNS resolution failure or connection timeout

### Troubleshooting Steps

1. **Confirm sandbox network policy**

```python
from ucloud_sandbox import Sandbox

# Default allows external network
sandbox = Sandbox.create(allow_internet_access=True)

# If external network is disabled
sandbox = Sandbox.create(allow_internet_access=False)  # Cannot access external network
```

2. **Check if network whitelist/blacklist is configured**

```python
from ucloud_sandbox import Sandbox, ALL_TRAFFIC

# Check if deny_out is misconfigured (blocking all outbound traffic)
sandbox = Sandbox.create(
    network={
        "deny_out": [ALL_TRAFFIC]
    }
)
```

3. **Network during template build**

If dependencies need to be downloaded during template build stage, ensure build environment has network access permissions.

>
> For details, see: [Network/Internet Access](/docs/agent-sandbox/sdk/sandbox/10-internet-access)

---

## Rate Limiting and Resource Restrictions

>
> For details, see: [Quota Description](/docs/agent-sandbox/rate-limit)

---

## Data Persistence Issues

### Symptoms
- Data not saved, lost after restart
- Failed to connect storage bucket

### Troubleshooting Steps

1. **Confirm written to correct persistence path**
2. **Check storage bucket connection parameters and permissions**
3. **Confirm using sandbox configuration that supports persistence**

>
> For details, see: [Data Persistence](/docs/agent-sandbox/sdk/sandbox/04-persistence), [Connect Storage Bucket](/docs/agent-sandbox/sdk/sandbox/11-connect-bucket)

---

## Still Have Issues?

If the above troubleshooting did not resolve your issue, please collect the following information and contact technical support:

- Sandbox ID / Template ID / Build ID
- Complete error messages and stack trace
- Reproduction steps
- SDK version and Python version