--- description: Error classes, codes, and context fields for @cloudflare/sandbox@next. title: Errors image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt > Use this file to discover all available pages before exploring further. # Errors Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/api/errors/index.md)|[Agent setup](https://9a51ac8b.previews.developers.cloudflare.com/agent-setup/) Path to Sandbox SDK 1.0 This page is the error reference for `@cloudflare/sandbox@next`, the preview of Sandbox SDK 1.0\. When to retry or relaunch: [Errors and recovery](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/errors/). Error classes and codes returned by the Sandbox SDK 1.0 preview, with short recommended actions. For full recovery procedures, refer to [Errors and recovery](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/errors/). ## How errors are returned Operations throw exceptions you can catch. Prefer `instanceof` on classes from `@cloudflare/sandbox`. Use `code` and `context` for metrics and stable field access. ```js import { ContainerUnavailableError, OperationInterruptedError, RPCTransportError, } from "@cloudflare/sandbox"; try { await sandbox.exec(["npm", "test"], { cwd: "/workspace/app" }); } catch (error) { if (error instanceof ContainerUnavailableError) { // error.code === "CONTAINER_UNAVAILABLE" // error.context.reason, error.context.retryAfterMs } if (error instanceof OperationInterruptedError) { // Convenience getters: error.reason, error.retryable, error.operationName // admitted is only on context: error.context.admitted } if (error instanceof RPCTransportError) { // Convenience getters: error.kind, error.originalMessage } } ``` ```ts import { ContainerUnavailableError, OperationInterruptedError, RPCTransportError, } from "@cloudflare/sandbox"; try { await sandbox.exec(["npm", "test"], { cwd: "/workspace/app" }); } catch (error) { if (error instanceof ContainerUnavailableError) { // error.code === "CONTAINER_UNAVAILABLE" // error.context.reason, error.context.retryAfterMs } if (error instanceof OperationInterruptedError) { // Convenience getters: error.reason, error.retryable, error.operationName // admitted is only on context: error.context.admitted } if (error instanceof RPCTransportError) { // Convenience getters: error.kind, error.originalMessage } } ``` ### Imports Common lifecycle, process, terminal, and backup errors are available from the package root: ```js import { ContainerUnavailableError, OperationInterruptedError, RPCTransportError, StaleProcessHandleError, // ... } from "@cloudflare/sandbox"; ``` ```ts import { ContainerUnavailableError, OperationInterruptedError, RPCTransportError, StaleProcessHandleError, // ... } from "@cloudflare/sandbox"; ``` The full module also exports `ErrorCode`, `SandboxError`, `createErrorFromResponse`, and other domain errors (files, ports, interpreter, mounts, and related context types): ```js import { ErrorCode, SandboxError, createErrorFromResponse, FileNotFoundError, // ... } from "@cloudflare/sandbox/errors"; ``` ```ts import { ErrorCode, SandboxError, createErrorFromResponse, FileNotFoundError, // ... } from "@cloudflare/sandbox/errors"; ``` Platform helpers (not `SandboxError` subclasses): ```js import { isPlatformTransientError, isDurableObjectCodeUpdateReset, } from "@cloudflare/sandbox"; ``` ```ts import { isPlatformTransientError, isDurableObjectCodeUpdateReset, } from "@cloudflare/sandbox"; ``` ### `SandboxError` shape Most SDK errors extend `SandboxError`: | Member | Description | | ---------- | ------------------------------------------------------------ | | name | Class name (for example ContainerUnavailableError) | | message | Human-readable message | | code | Stable ErrorCode string (for example CONTAINER\_UNAVAILABLE) | | context | Structured fields for the error type | | httpStatus | Mapped HTTP status when applicable | | operation | Operation label when provided | | suggestion | Optional actionable suggestion | | timestamp | ISO timestamp when provided | | toJSON() | Serializes the error fields for logs | `RuntimeIdentityInactiveError` extends `Error` directly (not `SandboxError`). It means the current container is no longer the active one for this handle or call. Tables include a **Recommended fix** column. For longer recovery procedures, refer to [Errors and recovery](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/errors/). Availability errors and deployment mismatch errors are listed in separate sections. Do not use the same retry loop for both. --- ## Container availability and interrupted calls These errors come from ordinary start, idle stop, replace, or lost contact while a call is running. | Class | Code | Key context | Details | Recommended fix | | ---------------------------- | ---------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | ContainerUnavailableError | CONTAINER\_UNAVAILABLE | reason, retryable: true, retryAfterMs? | Container not ready before the operation started. | Back off (honor retryAfterMs when set), then try the same kind of work again. | | OperationInterruptedError | OPERATION\_INTERRUPTED | reason, operation, admitted, retryable | Container or sandbox changed after the operation may have started. | Read reason and retryable. Check sandbox or app state before repeating work that changes state. | | RPCTransportError | RPC\_TRANSPORT\_ERROR | kind, originalMessage, errorName, closeCode? | SDK lost contact with the container during a call. | A later call may work. This call may already have changed something. | | RuntimeIdentityInactiveError | โ€” | โ€” | Current container is no longer active for this call or handle. Plain Error, not SandboxError. | Check whether the resource still exists; if not, start the work again from stored state. | ### `ContainerUnavailableError` reasons `context.reason`: | Reason | Meaning | | -------------------- | ---------------------------------------------------- | | container\_starting | Container is still starting | | container\_unhealthy | Container is not healthy | | container\_replaced | Container was replaced | | rpc\_upgrade\_failed | Could not establish communication with the container | ### `OperationInterruptedError` reasons `reason` / `context.reason`: | Reason | Meaning | | -------------------------- | ------------------------------------------ | | runtime\_replaced | Underlying container instance was replaced | | container\_stopped | Container stopped | | transport\_disposed | Communication session was disposed | | sandbox\_destroyed | Sandbox was destroyed | | sandbox\_lifetime\_changed | Sandbox lifetime configuration changed | | recovery\_exhausted | Recovery attempts were exhausted | | unknown | Unclassified interruption | Convenience getters on the error: `reason`, `retryable`, and `operationName`. Other fields such as `admitted`, `operationId`, `phase`, and backup-related metadata are on `error.context` only (`admitted` is `true | "unknown"`). ### `RPCTransportError` kinds `kind` / `context.kind`: | Kind | Meaning | | ------------------ | ------------------------------ | | peer\_closed | Peer closed the connection | | connection\_failed | Connection failed | | upgrade\_failed | Connection setup failed | | invalid\_frame | Unexpected frame | | protocol\_error | Frame rejected by the protocol | | session\_disposed | Session disposed | | unknown | Unclassified failure | --- ## Worker and container image mismatch These failures usually mean the Worker package and container image do not match, the image cannot start, or setup metadata does not match what the SDK expects. Fix the deployment. Do not treat them like a slow container start. Deploy the Worker package and the sandbox container image from the same `@cloudflare/sandbox@next` line. A preview Worker with a stable image (or the reverse) often fails here. | Class | Code | Key context | Details | Recommended fix | | --------------------------- | --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | RuntimeControlProtocolError | INTERNAL\_ERROR | reason | Worker and container could not complete setup together (metadata or protocol mismatch). The code is the shared INTERNAL\_ERROR value โ€” identify this class with instanceof RuntimeControlProtocolError or by pairing code === "INTERNAL\_ERROR" with context.reason. | Deploy the Worker package and container image from the same release line. Fix configuration if needed. | ### `RuntimeControlProtocolError` reasons `context.reason`: | Reason | Meaning | Notes | | ---------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- | | unsupported-protocol-version | Worker and container protocol versions do not match | Worker package and container image are not from the same release | | missing-metadata | Required setup metadata missing from the container | Bad or incomplete image/build | | malformed-metadata | Setup metadata could not be parsed | Bad or incomplete image/build | | activation-mismatch | Activation did not match the expected container | Can appear after container replace; if it keeps happening, check Worker and image pairing | The following permanent problems are related and return the same response: | Problem | Recommended fix | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Wrong or missing container image in wrangler / registry | Deploy the Worker package and container image from the same release line. Fix configuration if needed. | | Container exits before it becomes ready | Fix the image or entrypoint and redeploy. Do not only retry the app call. | | Account or location capacity limits | Refer to [Production capacity limits](#production-capacity-limits) | --- ## Process | Class | Code | Key context | Details | Recommended fix | | ------------------------------ | ------------------------------ | --------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | ProcessNotFoundError | PROCESS\_NOT\_FOUND | processId | Unknown process ID in the current container. | Use the correct ID, or start the process again from stored state. | | StaleProcessHandleError | STALE\_PROCESS\_HANDLE | processId, pid, operation | Handle or ID from a previous container. | Start the work again from stored state. Do not reuse the old handle. | | ProcessSpawnFailedError | PROCESS\_SPAWN\_FAILED | processId, command, cwd?, stderr? | Process could not start. | Correct the path, environment, command, or other arguments. Do not retry the same invalid request. | | InvalidProcessCwdError | INVALID\_PROCESS\_CWD | cwd, reason | Invalid working directory. | Correct the path, environment, command, or other arguments. Do not retry the same invalid request. | | InvalidProcessEnvironmentError | INVALID\_PROCESS\_ENVIRONMENT | name?, reason | Invalid environment overlay. | Correct the path, environment, command, or other arguments. Do not retry the same invalid request. | | InvalidProcessCursorError | INVALID\_PROCESS\_CURSOR | processId, cursor?, reason | Bad log cursor. | Correct the cursor or other arguments. Do not retry the same invalid value. | | ProcessWaitTimeoutError | PROCESS\_WAIT\_TIMEOUT | processId, operation, timeout | Local output, waitForExit, or waitForLog timed out. | The wait ended. The process or terminal may still be running. | | ProcessAbortedError | PROCESS\_ABORTED | processId, operation | Local AbortSignal ended a wait or stream. | The wait ended. The process or terminal may still be running. | | ProcessReadyTimeoutError | PROCESS\_READY\_TIMEOUT | processId, command, condition, timeout | Readiness wait timed out. | Check whether the process is still running before starting another. | | ProcessExitedBeforeReadyError | PROCESS\_EXITED\_BEFORE\_READY | processId, command, condition, exitCode | Process exited before readiness. | Correct the command or environment, then start again if needed. | | ProcessExitedBeforeLogError | PROCESS\_EXITED\_BEFORE\_LOG | processId, pid, exit | Process exited before a log match. | Correct the command or environment, then start again if needed. | | ProcessError | PROCESS\_ERROR | processId, pid?, exitCode?, stderr? | General process failure. | Check sandbox or app state before repeating work that changes state. | `getProcess` and `listProcesses` returning `null` or `[]` is not an error. --- ## Terminal | Class | Code | Key context | Details | Recommended fix | | -------------------------- | ------------------------- | ------------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | TerminalNotFoundError | TERMINAL\_NOT\_FOUND | terminalId | Unknown terminal ID in the current container. | Use the correct ID, or start the terminal again from stored state. | | StaleTerminalHandleError | STALE\_TERMINAL\_HANDLE | terminalId, operation | Handle or ID from a previous container. | Start the work again from stored state. Do not reuse the old handle. | | InvalidTerminalCwdError | INVALID\_TERMINAL\_CWD | terminalId, cwd, reason | Invalid working directory at create. | Correct the path, environment, command, or other arguments. Do not retry the same invalid request. | | InvalidTerminalCursorError | INVALID\_TERMINAL\_CURSOR | terminalId, cursor?, reason | Bad output cursor. | Correct the cursor or other arguments. Do not retry the same invalid value. | | TerminalControlError | TERMINAL\_CONTROL\_ERROR | terminalId, operation, reason? | Interrupt, terminate, resize, or related control failed. | Check sandbox or app state before repeating work that changes state. | `getTerminal` and `listTerminals` returning `null` or `[]` is not an error. --- ## Backup | Class | Code | Details | Recommended fix | | ------------------------ | ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | | BackupCreateError | BACKUP\_CREATE\_FAILED | Backup create failed. | Check failure details; correct options if they are invalid. | | BackupRestoreError | BACKUP\_RESTORE\_FAILED | Backup restore failed. | Check failure details; correct options if they are invalid. | | BackupNotFoundError | BACKUP\_NOT\_FOUND | Unknown backup ID. | Correct the path, environment, command, or other arguments. Do not retry the same invalid request. | | BackupExpiredError | BACKUP\_EXPIRED | Backup past validity. | Correct options, or create a new backup. | | InvalidBackupConfigError | INVALID\_BACKUP\_CONFIG | Invalid backup options. | Correct the path, environment, command, or other arguments. Do not retry the same invalid request. | --- ## Other domains These classes are available from `@cloudflare/sandbox/errors` (and some mount helpers from the package root). Confirm details against your installed package. Preview-specific guides for every domain are not all published yet. | Domain | Examples | Recommended fix | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | Filesystem | FileNotFoundError, FileExistsError, PermissionDeniedError, FileTooLargeError, FileSystemError | Correct the path or handle a missing file. | | Ports / preview | PortAlreadyExposedError, PortNotExposedError, InvalidPortError, PortInUseError, ServiceNotRespondingError, CustomDomainRequiredError | Correct port options or expose settings. | | Interpreter (extension) | InterpreterNotReadyError, ContextNotFoundError, CodeExecutionError | If the interpreter is not ready, back off and try again. Otherwise correct the request. | | Mounts | BucketMountError, BucketUnmountError, S3FSMountError, MissingCredentialsError, InvalidMountConfigError | Correct mount options or credentials. | | Validation | ValidationFailedError | Correct the path, environment, command, or other arguments. Do not retry the same invalid request. | Other domain classes may exist on `@cloudflare/sandbox/errors` in your installed package. Confirm against that package before depending on undocumented surfaces. Mount-related errors are also exported from `@cloudflare/sandbox` next to the mount APIs. --- ## Platform helpers | Helper | Details | Recommended fix | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | isPlatformTransientError(error) | True for some transient platform signals (for example connection lost, certain Durable Object storage startup resets, or retryable platform errors). | Prefer a new request or operation. | | isDurableObjectCodeUpdateReset(error) | True when the Durable Object isolate was replaced by a code update or deploy. | Do not keep retrying inside the same request. Let a new request run on the new isolate. | These helpers complement `SandboxError` subclasses. They do not replace the recovery rules on [Errors and recovery](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/errors/). --- ## Production capacity limits In production, the Containers platform may reject work when account or deployment limits are exceeded (for example `SURPASSED_BASE_LIMITS`, `SURPASSED_TOTAL_LIMITS`, `LOCATION_SURPASSED_BASE_LIMITS`). Retrying the same overload does not fix that. Reduce concurrency, raise limits, or fail to an operator path. These limits usually do not appear in local `wrangler dev`. Refer to [Platform limits](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/platform/limits/). --- ## Related * [Errors and recovery](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/errors/) * [Sandbox lifecycle](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/lifecycle/) * [Processes API](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/api/processes/) * [Terminals API](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/api/terminals/) * [Migrate](https://9a51ac8b.previews.developers.cloudflare.com/sandbox/1-0-preview/migrate/) Was this helpful? YesNo ## On this page [![](https://9a51ac8b.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://9a51ac8b.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/1-0-preview/api/errors/#page","headline":"Errors ยท Cloudflare Sandbox SDK docs","description":"Error classes, codes, and context fields for @cloudflare/sandbox@next.","url":"https://developers.cloudflare.com/sandbox/1-0-preview/api/errors/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```