Error Codes

This topic first provides common error categories and a recommended troubleshooting order. Formal error codes, error structures, and retry strategies should follow future product documentation.

Authentication and endpoints

Common symptoms:

• The SDK or CLI returns unauthenticated, unauthorized, or request failure errors.

• The SDK works but the CLI does not.

• The same API key works in one environment but fails in another.

Check the following first:

• Whether E2B_API_KEY is an FC Agent Sandbox API key created as described in Create an API Key.

• Whether the CLI version supports E2B_API_KEY authentication.

• Whether both E2B_API_URL and E2B_DOMAIN point to FC Agent Sandbox endpoints.

• Whether the API key, endpoint, template, and sandbox belong to the same account and region.

• Whether an expired, deleted, or insufficient-permission API key is being used in the current environment.

Template and sandbox creation

Common symptoms:

• Sandbox creation fails.

• The specified template does not exist or is unavailable.

• Creation takes too long, times out, or returns quota-related errors.

Check the following first:

• Whether the template name or template ID is correct.

• Whether the template build status is ready.

• Whether the current account, region, and template match.

• Whether the current account has reached sandbox concurrency, template build, or resource specification quotas.

• Whether the timeout, environment variables, and metadata size in the creation parameters comply with SDK and product constraints.

Connect, pause, and terminate

Common symptoms:

• Sandbox.connect() fails.

• A paused sandbox cannot be resumed.

• Access continues after kill() and then fails unexpectedly.

Check the following first:

• Whether sandboxId belongs to the current account and region.

• Whether the sandbox has already been terminated, reclaimed after timeout, or exited abnormally.

• Whether the API key and endpoint used for connection are the same as those used during creation.

• Whether the business code called kill() too early after the task finished.

After a sandbox is terminated, it cannot be connected to or resumed. Allowlisted accounts can use pause and resume to preserve the execution scene and record the corresponding sandboxId in business state.

Command execution

Common symptoms:

• A command returns a non-zero exit code.

• A long-running task produces no output, hangs, or is terminated by timeout.

• An interactive command behaves differently from the local terminal.

Check the following first:

• Whether the command depends on the current working directory, environment variables, network access, or local files.

• Whether PTY is required. Use PTY only for interactive CLIs, colored output, progress bars, or commands that depend on TTY detection.

• Whether the command timeout or sandbox timeout is too short.

• Whether stdout and stderr are correctly read and recorded by the business code.

• Whether user input is validated to avoid shell injection or accidental file deletion.

File read and write

Common symptoms:

• A file does not exist, permissions are insufficient, or the path is invalid.

• A write succeeds, but a later command cannot read the file.

• Uploading or downloading large files fails.

Check the following first:

• Whether you are using an absolute path inside the sandbox.

• Whether the file was written to the same sandbox where the command is running.

• Whether the directory has already been created, and whether the path differs only by case.

• Whether the file size, file count, or path depth exceeds product or SDK limits.

• Whether the local sandbox filesystem is being treated incorrectly as persistent storage across sandboxes.

Code Interpreter

Common symptoms:

• runCode() / run_code() fails.

• Variable state across multiple executions is not what you expected.

• Charts, rich media, or file outputs are unavailable.

Check the following first:

• Whether the template supports Code Interpreter.

• Whether required dependencies are installed in the template or the current sandbox.

• Whether code that needs shared state is executed in the same context.

• Whether the output type is within the currently compatible scope.

• Whether the code accesses missing files, restricted networks, or exceeds resource quotas.

Limited or unsupported capabilities

If the error comes from any of the following capabilities, do not treat it as a parameter problem first:

• Logs and Network Config Update: currently limited capabilities and not suitable as production dependencies.

• Custom file metadata: not currently supported by FC Agent Sandbox. The SDK can raise TemplateException: File metadata requires envd 0.6.2 or later. This is not a Python parameter error, and regular file reads and writes are unaffected.

• Snapshots, Volume, Team management, and API key / access token management: not currently part of the FC Agent Sandbox E2B compatibility path.

• E2B-hosted MCP Gateway, custom domains, proxy tunnels, and Bring Your Own Cloud: should not be copied directly into an FC Agent Sandbox integration plan.

Sandbox Metrics currently supports viewing CPU, memory, disk, and related metrics at 1-minute granularity. Use the Function Compute console, CloudMonitor, or Simple Log Service as the formal source of truth for billing, alerting, and capacity governance.

When you encounter one of these problems, return first to E2B SDK-compatible API List to confirm the capability boundary, and then decide whether you need an alternative design.