This guide helps you diagnose and resolve common problems when you use the CoreWeave sandbox Python client. Use it to identify the cause of an error and apply a fix. It also explains which conditions trigger each error so you can avoid them later.
Authentication issues
This section covers errors that occur when the SDK can’t find or validate your credentials.
Symptom: CWSandboxAuthenticationError or WandbAuthError raised on sandbox operations.
The SDK resolves authentication in this order:
CWSANDBOX_API_KEY env var (takes priority), a CoreWeave API Access TokenWANDB_API_KEY + WANDB_ENTITY_NAME env vars~/.netrc (api.wandb.ai) + WANDB_ENTITY_NAME
You need one of these configured. Check which method you’re using:
# Option 1: CoreWeave API Access Token (recommended)
echo $CWSANDBOX_API_KEY
# Option 2: W&B credentials
echo $WANDB_API_KEY
echo $WANDB_ENTITY_NAME
Common issues
| Issue | Solution |
|---|
| No credentials configured | Set CWSANDBOX_API_KEY or W&B credentials |
| Invalid or expired token | Create a new API Access Token from the Cloud Console |
| W&B API key set but entity missing | Set WANDB_ENTITY_NAME to your W&B entity/team |
| Using netrc but entity missing | Set WANDB_ENTITY_NAME. It’s always required for W&B |
| Netrc parse errors | Check ~/.netrc file syntax and permissions |
Command execution issues
This section covers problems related to running commands inside a sandbox, including timeouts, long-running processes, and how to interpret exit codes.
Timeout tuning
The difference between client-side and server-side timeouts helps you choose the right setting when a command takes longer than expected. The SDK has two types of timeouts:
| Timeout | Scope | Default | Where set |
|---|
timeout_seconds | Per-exec | None | exec() parameter |
max_lifetime_seconds | Sandbox lifetime | Backend-controlled | SandboxDefaults |
timeout_seconds):
from cwsandbox import SandboxTimeoutError
try:
result = sandbox.exec(
["python", "slow_script.py"],
timeout_seconds=60.0, # 60 second timeout
).result()
except SandboxTimeoutError:
print("Command timed out")
max_lifetime_seconds):
from cwsandbox import SandboxDefaults
defaults = SandboxDefaults(
container_image="python:3.11",
max_lifetime_seconds=3600, # Sandbox terminates after 1 hour
)
Long-running commands
Issue: Command takes longer than expected.
Solutions:
- Set an appropriate timeout:
process = sandbox.exec(
["pip", "install", "tensorflow"],
timeout_seconds=300.0, # 5 minutes for large packages
)
result = process.result()
- Use streaming to monitor progress:
process = sandbox.exec(["pip", "install", "tensorflow"])
for line in process.stdout:
print(line, end="")
result = process.result()
Exit code interpretation
Issue: You need to understand command failures.
Exit codes follow Unix conventions:
| Code | Meaning |
|---|
| 0 | Success |
| 1 | General error |
| 2 | Misuse of command |
| 126 | Command not executable |
| 127 | Command not found |
| 128+N | Killed by signal N |
check=True to raise on non-zero exit:
from cwsandbox import SandboxExecutionError
try:
result = sandbox.exec(
["python", "-c", "import nonexistent"],
check=True,
).result()
except SandboxExecutionError as e:
print(f"Exit code: {e.exec_result.returncode}")
print(f"stderr: {e.exec_result.stderr}")
Streaming output issues
This section covers issues that affect how output from a sandbox command appears in your client.
Line buffering behavior
Issue: Output appears delayed or all at once when streaming.
Python buffers stdout when not connected to a TTY. Force unbuffered output:
# Option 1: Use -u flag
process = sandbox.exec(["python", "-u", "script.py"])
for line in process.stdout:
print(line, end="")
result = process.result()
# Option 2: Set PYTHONUNBUFFERED
process = sandbox.exec(["sh", "-c", "PYTHONUNBUFFERED=1 python script.py"])
for line in process.stdout:
print(line, end="")
result = process.result()
print("Progress...", flush=True)
Cleanup problems
This section covers situations where sandboxes aren’t released as expected. These situations can lead to unnecessary cost and resource consumption.
Orphaned sandboxes
Issue: Sandboxes remain running after script exits or crashes.
Prevention: Use context managers:
# Recommended: automatic cleanup
with Sandbox.run() as sandbox:
result = sandbox.exec(["echo", "hello"]).result()
# Sandbox stopped automatically
Common error messages
The following table summarizes the most common exceptions that the SDK raises, along with their typical causes and recommended fixes.
| Error | Cause | Solution |
|---|
CWSandboxAuthenticationError | Missing or invalid credentials | Check CWSANDBOX_API_KEY is set |
WandbAuthError: WANDB_ENTITY_NAME is not set | W&B API key found but entity missing | Set WANDB_ENTITY_NAME env var |
SandboxNotRunningError | Operation on stopped sandbox | Check sandbox.status before operations |
SandboxTimeoutError | Operation exceeded timeout | Increase timeout_seconds or optimize command |
SandboxTerminatedError | Sandbox ended externally | Check max_lifetime_seconds or external termination |
SandboxFailedError | Sandbox failed to start | Check container image and resources |
SandboxNotFoundError | Sandbox deleted or never existed | Verify sandbox ID is correct |
SandboxExecutionError | Command returned non-zero (with check=True) | Check e.exec_result.stderr for details |
SandboxFileError | File operation failed | Check file path and permissions |
FunctionSerializationError | Can’t serialize function args | Use JSON-serializable types or Serialization.PICKLE |
AsyncFunctionError | Async function passed to @session.function() | Use sync functions only |
Last modified on May 29, 2026
