Skip to main content
This page covers BoxLite’s error types for structured error handling and the metrics API for monitoring runtime and per-box resource usage.

​
Error Types

import { BoxliteError, ExecError, TimeoutError, ParseError } from 'boxlite';

​
Exception Hierarchy

BoxliteError (base)
+-- ExecError       # Command failed
+-- TimeoutError    # Operation timeout
+-- ParseError      # Output parsing failed

​
BoxliteError

Base error class for all BoxLite errors. All specific error types extend this class. 
try {
  await box.exec('invalid-command');
} catch (err) {
  if (err instanceof BoxliteError) {
    console.error('BoxLite error:', err.message);
  }
}
Always catch BoxliteError as a fallback when you want to handle any BoxLite-specific error generically.

​
ExecError

Command execution failed (non-zero exit code).
PropertyTypeDescription
commandstringFailed command
exitCodenumberNon-zero exit code
stderrstringStandard error output
try {
  await box.exec('false');
} catch (err) {
  if (err instanceof ExecError) {
    console.error(`Command: ${err.command}`);
    console.error(`Exit code: ${err.exitCode}`);
    console.error(`Stderr: ${err.stderr}`);
  }
}

​
TimeoutError

Operation exceeded time limit. 
try {
  await desktop.waitUntilReady(5);
} catch (err) {
  if (err instanceof TimeoutError) {
    console.error('Desktop did not become ready');
  }
}

​
ParseError

Failed to parse command output. 
try {
  const pos = await desktop.cursorPosition();
} catch (err) {
  if (err instanceof ParseError) {
    console.error('Failed to parse cursor position');
  }
}

​
Comprehensive Error Handling

Here is a pattern for handling all BoxLite error types: 
import { BoxliteError, ExecError, TimeoutError, ParseError } from 'boxlite';

try {
  const result = await box.exec('some-command');
} catch (err) {
  if (err instanceof ExecError) {
    console.error(`Command "${err.command}" failed with exit code ${err.exitCode}`);
    console.error(`Stderr: ${err.stderr}`);
  } else if (err instanceof TimeoutError) {
    console.error('Operation timed out:', err.message);
  } else if (err instanceof ParseError) {
    console.error('Failed to parse output:', err.message);
  } else if (err instanceof BoxliteError) {
    console.error('BoxLite error:', err.message);
  } else {
    throw err;  // Re-throw unknown errors
  }
}

​
Metrics

BoxLite provides two levels of metrics: runtime-wide metrics and per-box metrics.

​
JsRuntimeMetrics

Runtime-wide metrics covering all boxes managed by a runtime instance.
FieldTypeDescription
boxesCreatedTotalnumberTotal boxes created
boxesFailedTotalnumberBoxes that failed during creation
numRunningBoxesnumberCurrently running boxes
totalCommandsExecutednumberTotal commands executed
totalExecErrorsnumberTotal execution errors
const metrics = await runtime.metrics();
console.log(`Boxes created: ${metrics.boxesCreatedTotal}`);
console.log(`Running: ${metrics.numRunningBoxes}`);

​
JsBoxMetrics

Per-box resource metrics for monitoring individual box usage.

​
Counter Fields

FieldTypeDescription
commandsExecutedTotalnumberCommands executed on this box
execErrorsTotalnumberExecution errors on this box
bytesSentTotalnumberBytes sent via stdin
bytesReceivedTotalnumberBytes received via stdout/stderr

​
Resource Fields

FieldTypeDescription
cpuPercentnumber | undefinedCPU usage (0.0-100.0)
memoryBytesnumber | undefinedMemory usage in bytes
networkBytesSentnumber | undefinedNetwork bytes sent
networkBytesReceivednumber | undefinedNetwork bytes received
networkTcpConnectionsnumber | undefinedCurrent TCP connections
networkTcpErrorsnumber | undefinedTotal TCP errors

​
Timing Fields (milliseconds)

FieldTypeDescription
totalCreateDurationMsnumber | undefinedTotal create time
guestBootDurationMsnumber | undefinedGuest agent ready time
stageFilesystemSetupMsnumber | undefinedDirectory setup time
stageImagePrepareMsnumber | undefinedImage pull/prepare time
stageGuestRootfsMsnumber | undefinedRootfs bootstrap time
stageBoxConfigMsnumber | undefinedConfiguration build time
stageBoxSpawnMsnumber | undefinedSubprocess spawn time
stageContainerInitMsnumber | undefinedContainer init time

​
Example

const metrics = await box.metrics();
console.log(`CPU: ${metrics.cpuPercent}%`);
console.log(`Memory: ${(metrics.memoryBytes || 0) / (1024 * 1024)} MB`);
console.log(`Boot time: ${metrics.guestBootDurationMs}ms`);

​
Monitoring Dashboard Example

Here is a more complete example that polls both runtime and box metrics: 
import { JsBoxlite, SimpleBox } from 'boxlite';

const runtime = JsBoxlite.withDefaultConfig();

// Create a box
await using box = new SimpleBox({
  image: 'alpine:latest',
  runtime
});

// Run some commands
await box.exec('echo', 'hello');
await box.exec('sleep', '1');

// Check runtime metrics
const runtimeMetrics = await runtime.metrics();
console.log('--- Runtime Metrics ---');
console.log(`Total boxes created: ${runtimeMetrics.boxesCreatedTotal}`);
console.log(`Running boxes: ${runtimeMetrics.numRunningBoxes}`);
console.log(`Commands executed: ${runtimeMetrics.totalCommandsExecuted}`);
console.log(`Exec errors: ${runtimeMetrics.totalExecErrors}`);