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.

Operations throw exceptions you can catch. Prefer instanceof on classes from @cloudflare/sandbox. Use code and context for metrics and stable field access.

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
	}
}

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
	}
}

Common lifecycle, process, terminal, and backup errors are available from the package root:

import {
	ContainerUnavailableError,
	OperationInterruptedError,
	RPCTransportError,
	StaleProcessHandleError,
	// ...
} from "@cloudflare/sandbox";

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):

import {
	ErrorCode,
	SandboxError,
	createErrorFromResponse,
	FileNotFoundError,
	// ...
} from "@cloudflare/sandbox/errors";

import {
	ErrorCode,
	SandboxError,
	createErrorFromResponse,
	FileNotFoundError,
	// ...
} from "@cloudflare/sandbox/errors";

Platform helpers (not SandboxError subclasses):

import {
	isPlatformTransientError,
	isDurableObjectCodeUpdateReset,
} from "@cloudflare/sandbox";

import {
	isPlatformTransientError,
	isDurableObjectCodeUpdateReset,
} from "@cloudflare/sandbox";

Most SDK errors extend SandboxError:

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.

Availability errors and deployment mismatch errors are listed in separate sections. Do not use the same retry loop for both.

These errors come from ordinary start, idle stop, replace, or lost contact while a call is running.

context.reason:

reason / context.reason:

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").

kind / context.kind:

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.

context.reason:

The following permanent problems are related and return the same response:

getProcess and listProcesses returning null or [] is not an error.

getTerminal and listTerminals returning null or [] is not an error.

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.

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.

These helpers complement SandboxError subclasses. They do not replace the recovery rules on Errors and recovery.

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.

• Errors and recovery
• Sandbox lifecycle
• Processes API
• Terminals API
• Migrate