Handle errors and timeouts

Devbox operations distinguish command results from operation failures. Use operation options to cancel or time out work, and catch typed SDK or Connect errors when an operation cannot produce its normal result.

`OperationOptions`

Devbox methods that perform remote work accept signal and timeoutMs, either directly or through a method-specific options type.

interface OperationOptions {
  signal?: AbortSignal;
  timeoutMs?: number;
}

AbortSignal

Cancels the operation when the signal is aborted. An already-aborted signal prevents the operation from starting.

number

The operation’s timeout budget in milliseconds.

For connection-backed operations with multiple phases, such as activating a stopped Devbox and then connecting to it, timeoutMs must be finite and non-negative and establishes one deadline shared by all phases. It is not reset after activation or connection. A timeout rejects with DevboxTimeoutError. Resource RPCs pass the timeout to Connect and can instead reject with a ConnectError whose code is DeadlineExceeded.

Example

Set a 30-second budget for activation, connection, and command execution:

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.exec(["npm", "test"], {
  timeoutMs: 30_000,
});

Abort an operation from application code:

const controller = new AbortController();
process.once("SIGINT", () => controller.abort());

const devbox = await client.devboxes.get("sdk-example");
await devbox.exec(["npm", "test"], { signal: controller.signal });

When a connection-backed operation is aborted, it rejects with signal.reason if it is an Error. Otherwise it rejects with an Error whose name is "AbortError". Cancellation is not represented by a DevboxError subclass. See Use interactive terminals for terminal-specific signal behavior.

Command results and rejected operations

exec() and shell() resolve with an ExecResult when the remote command runs, including when it exits non-zero. Check exitCode, signal, and error instead of relying on catch for command failure.

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.shell("npm test");
if (result.exitCode !== 0) {
  throw new Error(result.error ?? result.stderr);
}

The promise rejects when the operation itself fails, including invalid input, abort, timeout, RPC or gateway failure, or an incomplete service response. fs.copy() and recursive fs.remove() run commands internally and reject with an ordinary Error when those helper commands fail. See Run commands for the complete ExecResult fields.

`ConnectError`

Namespace API failures surface as ConnectError from @connectrpc/connect. Inspect its Connect code for programmatic handling. Agent command DeadlineExceeded errors are converted to DevboxTimeoutError; other RPC deadline failures can remain ConnectError instances.

import { Code, ConnectError } from "@connectrpc/connect";

try {
  await client.devboxes.get("devbox-id");
} catch (error) {
  if (error instanceof ConnectError && error.code === Code.NotFound) {
    console.error("Devbox not found");
  } else {
    throw error;
  }
}

`DevboxError`

Base class for errors created by the Devbox SDK. Catch it to handle any SDK-level Devbox failure while allowing abort errors and ConnectError to follow separate paths.

class DevboxError extends Error

`DevboxTimeoutError`

The operation exhausted an SDK-managed timeoutMs budget. This can happen during a connection-backed operation’s activation, connection, handshake, or remote work, including command execution.

class DevboxTimeoutError extends DevboxError {
  constructor(message: string, readonly timeoutMs?: number);
}

number

The configured timeout in milliseconds when that value is available at the point where the error is created.

`DevboxGatewayError`

The Devbox gateway or display endpoint rejected a connection with an HTTP error. The status code is available for logging or conditional handling. Authentication failures commonly use status 401 or 403 and are not retried by the connection manager.

class DevboxGatewayError extends DevboxError {
  constructor(readonly statusCode: number);
}

number

required

The HTTP response status returned by the gateway.

`DevboxDisplayUnavailableError`

The Devbox does not expose the VNC display service. This appears when using devbox.display with a Devbox that has no graphical display.

class DevboxDisplayUnavailableError extends DevboxError

`IncompleteResponseError`

The service response omitted a field required to complete an operation. It can appear when a create, get, update, or lifecycle response lacks its Devbox value, or when a command stream ends without a final result.

class IncompleteResponseError extends DevboxError {
  constructor(context: string);
}

`ImageOptimizationError`

Image optimization reported failure, or its event stream ended before reporting completion.

class ImageOptimizationError extends DevboxError

Catch Devbox failures

Import Devbox error classes from @namespacelabs/sdk/devbox. Check specific classes before their DevboxError base class.

import {
  DevboxError,
  DevboxGatewayError,
  DevboxTimeoutError,
} from "@namespacelabs/sdk/devbox";

const devbox = await client.devboxes.get("sdk-example");

try {
  await devbox.exec(["npm", "test"], { timeoutMs: 60_000 });
} catch (error) {
  if (error instanceof DevboxTimeoutError) {
    console.error("The Devbox operation did not finish in time.");
  } else if (error instanceof DevboxGatewayError) {
    console.error(`Gateway returned HTTP ${error.statusCode}.`);
  } else if (error instanceof DevboxError) {
    console.error(error.message);
  } else {
    throw error;
  }
}

Handle aborts separately when cancellation is expected:

const devbox = await client.devboxes.get("sdk-example");

try {
  await devbox.exec(["sleep", "60"], { signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    return;
  }
  throw error;
}

Run commands

Interpret command exit codes and output.

Use interactive terminals

Open, close, and wait for terminal sessions.

Authenticate with Namespace

Configure credentials and handle authentication failures.

Devbox SDK

Automation

CLI

`OperationOptions`

Example

Command results and rejected operations

`ConnectError`

`DevboxError`

`DevboxTimeoutError`

`DevboxGatewayError`

`DevboxDisplayUnavailableError`

`IncompleteResponseError`

`ImageOptimizationError`

Catch Devbox failures

Run commands

Use interactive terminals

Authenticate with Namespace

​OperationOptions

​Example

​Command results and rejected operations

​ConnectError

​DevboxError

​DevboxTimeoutError

​DevboxGatewayError

​DevboxDisplayUnavailableError

​IncompleteResponseError

​ImageOptimizationError

​Catch Devbox failures

​Related documentation

Run commands

Use interactive terminals

Authenticate with Namespace

`OperationOptions`

Example

Command results and rejected operations

`ConnectError`

`DevboxError`

`DevboxTimeoutError`

`DevboxGatewayError`

`DevboxDisplayUnavailableError`

`IncompleteResponseError`

`ImageOptimizationError`

Catch Devbox failures

Related documentation