Troubleshooting - CoreWeave Docs

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. Which credential the SDK looks for depends on the authentication strategy you select. The SDK doesn’t fall back from one strategy to the other.

CoreWeave (default): reads CWSANDBOX_API_KEY, a CoreWeave API access token, and sends it as a bearer token. Requests go out unauthenticated when the variable isn’t set.
W&B: selected explicitly by passing auth=AuthStrategy.WANDB. Credential discovery is delegated to the wandb library, which accepts an active wandb login session, WANDB_API_KEY, or the api.wandb.ai entry in ~/.netrc.

Check which credential you have configured:

# CoreWeave API access token (the default strategy)
echo $CWSANDBOX_API_KEY

# W&B API key (requires auth=AuthStrategy.WANDB)
echo $WANDB_API_KEY

Common issues

Issue	Solution
No credentials configured	Set `CWSANDBOX_API_KEY`, or set a W&B credential and pass `auth=AuthStrategy.WANDB`
Invalid or expired token	Create a new API access token from the cloud console
W&B credential set but ignored	Pass `auth=AuthStrategy.WANDB`. The SDK doesn’t use a W&B credential unless you select the strategy
`W&B authentication requires the optional wandb dependency`	Install the extra with `uv pip install 'cwsandbox[wandb]'`
Sandbox lands in an unexpected entity or project	Set `WANDB_ENTITY` and `WANDB_PROJECT`. Both are optional; W&B uses your default entity and a `sandbox` project when they’re unset
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. For command execution, distinguish the operation timeout from the sandbox lifetime:

Timeout	Scope	Default	Where set
`timeout_seconds`	Per-exec	Omitted or `None`: uses `request_timeout_seconds`, which defaults to 300 seconds	`exec()` parameter
`max_lifetime_seconds`	Sandbox lifetime	Backend-controlled	`SandboxDefaults`

For the complete list of timeout settings and their defaults, see Timeouts. Client-side timeout (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")

Server-side lifetime (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

Use 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()

For your own scripts, flush explicitly:

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

See Cleanup patterns: orphan management for how to find and clean up orphaned sandboxes by tag.

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 the credential for your selected authentication method
`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

​Authentication issues

​Common issues

​Command execution issues

​Timeout tuning

​Long-running commands

​Exit code interpretation

​Streaming output issues

​Line buffering behavior

​Cleanup problems

​Orphaned sandboxes

​Common error messages