Errors

TL;DR

All @cmdop/node errors extend the base CMDOPError class. The hierarchy includes ConnectionError (timeout, relay), AuthenticationError (invalid key, expired token), MachineError (not found, offline), AgentError (timeout, schema validation), and BrowserError (session, navigation). Use instanceof checks to handle specific errors. Every error includes code, message, cause, and retryable properties.

All SDK errors extend the base CMDOPError class. Use instanceof checks for specific error handling.

What is the error hierarchy?


CMDOPError
├── ConnectionError
│   ├── TimeoutError
│   └── RelayError
├── AuthenticationError
│   ├── InvalidApiKeyError
│   └── ExpiredTokenError
├── MachineError
│   ├── MachineNotFoundError
│   └── MachineOfflineError
├── AgentError
│   ├── AgentTimeoutError
│   └── SchemaValidationError
└── BrowserError
    ├── SessionError
    └── NavigationError

How do I handle errors in general?


import { CMDOPError, MachineNotFoundError, AuthenticationError } from '@cmdop/node';
 
try {
  const client = await CMDOPClient.remote({ apiKey: 'cmdop_xxx' });
  await client.terminal.setMachine('prod-server');
  const { output } = await client.terminal.execute('ls');
} catch (error) {
  // Check from most specific to least specific using instanceof
  if (error instanceof MachineNotFoundError) {
    console.log('Machine not found:', error.machine);
  } else if (error instanceof AuthenticationError) {
    console.log('Auth failed:', error.message);
  } else if (error instanceof CMDOPError) {
    // Catch-all for any CMDOP error not matched above
    console.log('CMDOP error:', error.code, error.message);
  } else {
    // Re-throw non-CMDOP errors (network issues, etc.)
    throw error;
  }
}

How do I handle connection errors?


import { ConnectionError, TimeoutError, RelayError } from '@cmdop/node';
 
try {
  const client = await CMDOPClient.remote({ apiKey: 'cmdop_xxx' });
} catch (error) {
  if (error instanceof TimeoutError) {
    // The connection to the relay or machine timed out
    console.log('Connection timed out');
  } else if (error instanceof RelayError) {
    // The cloud relay server is unreachable
    console.log('Relay unreachable:', error.relayUrl);
  }
}

How do I handle authentication errors?


import { InvalidApiKeyError, ExpiredTokenError } from '@cmdop/node';
 
try {
  const client = await CMDOPClient.remote({ apiKey: 'invalid' });
} catch (error) {
  if (error instanceof InvalidApiKeyError) {
    // The API key format is invalid (e.g., missing "cmdop_" prefix)
    console.log('Invalid API key format');
  } else if (error instanceof ExpiredTokenError) {
    // The authentication token has expired and needs refreshing
    console.log('Token expired, refresh needed');
  }
}

How do I handle agent errors?


import { AgentTimeoutError, SchemaValidationError } from '@cmdop/node';
 
try {
  const result = await client.agent.run({
    prompt: 'Complex task',
    outputSchema: MySchema,
    timeout: 30000,
  });
} catch (error) {
  if (error instanceof AgentTimeoutError) {
    // The agent did not complete within the specified timeout
    console.log('Agent timed out after', error.timeoutMs, 'ms');
  } else if (error instanceof SchemaValidationError) {
    // The agent's output did not match the provided Zod schema
    console.log('Schema validation failed:', error.validationErrors);
  }
}

How do I handle browser errors?


import { SessionError, NavigationError } from '@cmdop/node';
 
try {
  const session = await client.browser.createSession({ machine: 'my-server' });
  await session.navigate('https://example.com');
} catch (error) {
  if (error instanceof SessionError) {
    // Failed to create or maintain the browser session
    console.log('Browser session failed:', error.message);
  } else if (error instanceof NavigationError) {
    // Page navigation failed (e.g., DNS error, HTTP error status)
    console.log('Navigation failed:', error.url, error.statusCode);
  }
}

What properties do errors include?

All errors include these properties:

Property	Type	Description
`code`	`string`	Machine-readable error code
`message`	`string`	Human-readable error message
`cause`	`Error`	Original error (if wrapped)
`retryable`	`boolean`	Whether the operation can be retried