Troubleshooting Cortex Sandboxes¶

This page describes how to diagnose and resolve common Cortex Sandboxes failures.

SDK errors¶

For a full list of SDK exceptions with meanings and remediation guidance, see Cortex Sandboxes error reference.

No connection could be resolved¶

If creating a sandbox raises snowflake.sandbox has no endpoint to talk to, the SDK found no connection at all. If it raises snowflake.sandbox could not resolve connection '<name>', it found the name you asked for but could not load it from ~/.snowflake/connections.toml. Configure one using any of:

• The default connection in ~/.snowflake/connections.toml or ~/.snowflake/config.toml.
• connection="my_connection" on the call itself. Every entry point takes it, including Sandbox.create(), Sandbox.connect(), Sandbox.list(), get_sandbox(), and destroy_sandbox(). Use with using("my_connection"): when several calls should share one connection. Both delegate to snowflake-connector-python, so all of its auth methods work.
• SNOWFLAKE_DEFAULT_CONNECTION_NAME, or default_connection_name in ~/.snowflake/config.toml, to choose which entry is the default.
• The SNOWFLAKE_ACCOUNT and SNOWFLAKE_PAT environment variables. SNOWFLAKE_PAT is read first; SNOWFLAKE_TOKEN is accepted as a fallback for an OAuth session token.

For the full set of options, see Connect to Snowflake from the SDK.

Inspect and recover a problematic container¶

When a command fails or the sandbox behaves unexpectedly:

1. Read the container output:

   Copy code

   logs = sb.logs(tail=200)
   

2. Replace the container if it is in a bad state — terminate it and create a fresh one:

   Copy code

   sb.terminate()
   sb = Sandbox.create(...)   # same arguments as before
   

3. For a detached run, sb.wait() returns the RunResult, including the exit code and result.

Arguments that are accepted but raise¶

Some parameters exist in a method signature but are rejected at call time, so the failure appears at runtime rather than as a type error. These are deliberate: each one previously failed silently, which was worse.

exec() and exec_stream() reject stdin:

sb.exec(["python", "-i"], stdin=b"print(1)\n")   # raises SandboxError

There is no way to write to a running process’s stdin. The only interactive input path is a PTY session through sb.shell(). Earlier releases accepted stdin and silently discarded it.

exec() also rejects text=False. Binary output must be written to a file inside the sandbox and fetched with sb.download_file(). exec_stream() has no text parameter at all, so passing one raises TypeError rather than SandboxError.

exec() further rejects env and working_dir. Pass those to exec_stream(cmd, env=..., working_dir=...) for a per-call value, or set env once at create time with Sandbox.create(env=...).

An empty command raises rather than reaching the server:

sb.exec([])   # raises SandboxError

Previously this ran as an empty shell and reported success, so a command that never ran returned exit_code=0.

Session.status() inside async code¶

Calling Session.status() from inside a running event loop raises SandboxError. Use the async accessor instead:

status = await session.status_async()

The synchronous status() is unchanged when no event loop is running. It raises in the async case because it previously returned a status fabricated from the session id rather than reading the real one.

CLI-specific issues¶

If snow sandbox reports No such command 'sandbox', the plugin is either still disabled or installed in a different Python environment from the snow you’re running. Snowflake CLI plugins install disabled, so run snow plugin enable snow-sandbox once per machine; it writes to ~/.snowflake/config.toml. Then check that which snow points at the environment where you installed snowflake-sandbox-python. If it still shows an older path right after installing, run hash -r or open a new terminal. Run snow plugin list to confirm snow-sandbox shows enabled = True.

If you want Snowflake CLI as an isolated tool, install the CLI as the tool and add this package to it: uv tool install snowflake-cli --with snowflake-sandbox-python, or with pipx, pipx install snowflake-cli then pipx inject snowflake-cli snowflake-sandbox-python. Running uv tool install 'snowflake-sandbox-python[cli]' fails with “No executables are provided by package”, because this package ships no executable of its own.

If snow sandbox commands fail to authenticate, confirm the active snow connection is set:

snow connection test
snow connection set-default my-conn

If snow sandbox run --app can’t find your module, verify the path points at the Python module that defines your App (for example, agent_app.py), not a directory. See Working with the Cortex Sandboxes CLI and the Cortex Sandboxes CLI reference.

Feature not enabled¶

If the Cortex Sandboxes service returns a “not enabled” or 403-style error, Cortex Sandboxes is likely not enabled on your account. Contact your Snowflake account representative to confirm.