Errors

import {
  CommandError,
  SandboxError,
  ExecConnectionError,
  WorkflowError,
  SandboxClientError,
} from "@alineo-labs/sandbox";

Error hierarchy

Error
├── WorkflowError            — base class for Sandbox-level errors
│   ├── SandboxError        — sandbox lifecycle failure: create/boot/Running, paused, unsupported fork(), or snapshot
│   ├── ExecConnectionError — execd not ready after retry window
│   └── CommandError        — non-zero exit code in strict mode
└── SandboxClientError                — client-level errors from Sandbox itself (not a WorkflowError)

SandboxError, ExecConnectionError, and CommandError all extend WorkflowError, which extends Error — catch all three with e instanceof WorkflowError. SandboxClientError is a separate, sibling class thrown by Sandbox client methods (sandbox(), resume(), sandboxes.*, environment()) rather than by Sandbox methods — see SandboxClientError below.

WorkflowError

Base class. Has message and name properties. name is always "WorkflowError".

import { WorkflowError } from "@alineo-labs/sandbox";

try {
  await sb.exec("cmd");
} catch (e) {
  if (e instanceof WorkflowError) {
    console.error("alineo error:", e.message);
  } else {
    throw e;
  }
}

CommandError

Thrown when sb.exec() exits with a non-zero code and strict: true (the default).

import { CommandError } from "@alineo-labs/sandbox";

try {
  await sb.exec("exit 42");
} catch (e) {
  if (e instanceof CommandError) {
    console.error(`exit ${e.exitCode}`); // 42
    console.error(`command: ${e.command}`); // "exit 42"
    console.error(`sandbox: ${e.sandboxId}`);
  }
}

Properties

Property	Type	Description
`exitCode`	`number`	The process exit code
`command`	`string`	The command string that was run
`sandboxId`	`string`	The sandbox ID where it ran
`message`	`string`	`"Command exited with code N: <cmd>"`
`name`	`string`	`"CommandError"`

Avoiding CommandError

Pass { strict: false } to get the exit code in the result:

const { exitCode } = await sb.exec("test -f /etc/hosts", { strict: false });

SandboxError

Thrown by methods on SandboxHandle itself: resume() if the container never reaches Running (or enters Failed/Terminated), an exec call while the sandbox is paused, fork() when the deps don't support it, or a failed snapshot wait.

A failure during client.sandbox()'s own initial creation throws SandboxClientError, not SandboxError — see below.

import { SandboxError } from "@alineo-labs/sandbox";

try {
  await sb.resume(); // sandbox previously pause()d, now stuck
} catch (e) {
  if (e instanceof SandboxError) {
    console.error(e.message); // e.g. "Sandbox entered Failed: ..." or "sandbox is paused — call resume() first"
    console.error(e.sandboxId ?? ""); // sandbox ID if assigned before failure
  }
}

Properties

Property	Type	Description
`sandboxId`	`string \| undefined`	Container ID if one was assigned before the failure
`message`	`string`	Describes what failed
`name`	`string`	`"SandboxError"`

ExecConnectionError

Thrown when the execd daemon inside the container never becomes ready within the retry window (~15 seconds). The container is Running from OpenSandbox's perspective, but the exec daemon isn't accepting connections.

import { ExecConnectionError } from "@alineo-labs/sandbox";

try {
  await sb.exec("echo test");
} catch (e) {
  if (e instanceof ExecConnectionError) {
    console.error(e.message); // "execd not ready for sandbox <id>"
    console.error(e.sandboxId); // the sandbox ID
  }
}

Properties

Property	Type	Description
`sandboxId`	`string`	The sandbox ID
`message`	`string`	`"execd not ready for sandbox <id>"`
`name`	`string`	`"ExecConnectionError"`

This usually means the container image doesn't include execd, or the container started but the execd process crashed.

SandboxClientError

Thrown by the Sandbox client for API-level errors (404 not found, timeouts waiting for Running state):

import { SandboxClientError } from "@alineo-labs/sandbox";

try {
  await client.resume("nonexistent-id");
} catch (e) {
  if (e instanceof SandboxClientError) {
    console.error(e.message); // "Session nonexistent-id not found"
    console.error(e.status); // 404
  }
}

SandboxClientError is not a WorkflowError — it's a separate class for client-level errors.

Errors

On this page