Error Handling

import {
  SandboxError,
  TimeoutError,
  NotFoundError,
  AuthenticationError,
  InvalidArgumentError,
  NotEnoughSpaceError,
  TemplateError,
  BuildError,
  FileUploadError,
  GitAuthError,
  GitUpstreamError,
  CommandExitError,
} from '@declaw/sdk';

Error
└── SandboxError
    ├── TimeoutError
    ├── NotFoundError
    ├── AuthenticationError
    ├── InvalidArgumentError
    ├── NotEnoughSpaceError
    ├── FileUploadError
    ├── GitAuthError
    ├── GitUpstreamError
    ├── CommandExitError
    └── TemplateError
        └── BuildError

class SandboxError extends Error {
  sandboxId?: string;
  code?: string;
  name: string; // set to the subclass name for `instanceof`-free discrimination

  constructor(message: string, opts?: { sandboxId?: string; code?: string });
}

import { Sandbox, TimeoutError } from '@declaw/sdk';

try {
  const result = await sbx.commands.run('sleep 300', { timeout: 10 });
} catch (err) {
  if (err instanceof TimeoutError) {
    console.error('Timed out in sandbox:', err.sandboxId);
  }
}

import { Sandbox, NotFoundError } from '@declaw/sdk';

try {
  const sbx = await Sandbox.connect('nonexistent-id', { apiKey: 'key', domain: 'host:8080' });
} catch (err) {
  if (err instanceof NotFoundError) {
    console.error('Sandbox not found');
  }
}

import { Sandbox, AuthenticationError } from '@declaw/sdk';

try {
  const sbx = await Sandbox.create({ apiKey: 'bad-key', domain: 'host:8080' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key');
  }
}

import { createTransformationRule, InvalidArgumentError } from '@declaw/sdk';

try {
  createTransformationRule({ match: '(a+)+', replace: 'safe' });
} catch (err) {
  if (err instanceof InvalidArgumentError) {
    console.error('Validation failed:', err.message);
  }
}

import { NotEnoughSpaceError } from '@declaw/sdk';

try {
  await sbx.files.write('/data/large.bin', hugeBuffer);
} catch (err) {
  if (err instanceof NotEnoughSpaceError) {
    console.error('Sandbox disk full');
  }
}

class CommandExitError extends SandboxError {
  exitCode: number;
  stdout: string;
  stderr: string;

  constructor(
    message: string,
    opts: { sandboxId?: string; exitCode: number; stdout: string; stderr: string },
  );
}

import { CommandExitError } from '@declaw/sdk';

const handle = await sbx.commands.run('python3 bad_script.py', { background: true });

try {
  const result = await handle.wait();
} catch (err) {
  if (err instanceof CommandExitError) {
    console.error(`Exit ${err.exitCode}: ${err.stderr}`);
  }
}

import { Template, BuildError } from '@declaw/sdk';

try {
  const info = await Template.build(template, 'alias', { apiKey: 'key', domain: 'host:8080' });
} catch (err) {
  if (err instanceof BuildError) {
    console.error('Build failed:', err.message);
  }
}

import { SandboxError } from '@declaw/sdk';

let sbx;
try {
  sbx = await Sandbox.create({ apiKey: 'key', domain: 'host:8080' });
  const result = await sbx.commands.run('my-command');
  console.log(result.stdout);
} catch (err) {
  if (err instanceof SandboxError) {
    console.error(`Declaw error [${err.name}]: ${err.message}`);
    if (err.sandboxId) {
      console.error('Sandbox ID:', err.sandboxId);
    }
  } else {
    throw err; // re-throw unexpected errors
  }
} finally {
  await sbx?.kill();
}

try {
  await sbx.kill();
} catch (err) {
  if (err instanceof SandboxError) {
    switch (err.name) {
      case 'NotFoundError':
        console.log('Already gone');
        break;
      case 'TimeoutError':
        console.log('Kill timed out');
        break;
      default:
        throw err;
    }
  }
}

import {
  CODE_IDEMPOTENCY_KEY_REUSED,
  CODE_TEMPLATE_NOT_READY,
} from '@declaw/sdk';

try {
  const sbx = await Sandbox.create({ template: 'python' });
} catch (e) {
  if (e instanceof SandboxError) {
    if (e.code === CODE_TEMPLATE_NOT_READY) {
      // Not retryable — the template needs a rebuild.
    } else if (e.code === CODE_IDEMPOTENCY_KEY_REUSED) {
      // Key reused with different parameters. The SDK generates a fresh key per
      // create, so this should not occur through it.
    }
  }
}

import { Sandbox, TimeoutError } from '@declaw/sdk';

async function runWithRetry(
  sbx: Sandbox,
  cmd: string,
  retries = 3,
): Promise<string> {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      const result = await sbx.commands.run(cmd, { timeout: 30 });
      return result.stdout;
    } catch (err) {
      if (err instanceof TimeoutError && attempt < retries - 1) {
        const delay = 1000 * Math.pow(2, attempt);
        await new Promise((r) => setTimeout(r, delay));
      } else {
        throw err;
      }
    }
  }
  throw new Error('unreachable');
}

const result = await sbx.commands.run('python3 risky.py');
if (result.exitCode !== 0) {
  console.error(`Failed (exit ${result.exitCode}):`, result.stderr);
} else {
  console.log(result.stdout);
}

await using sbx = await Sandbox.create({ apiKey: 'key', domain: 'host:8080' });
// sbx.close() is guaranteed on block exit even if an error is thrown
const result = await sbx.commands.run('npm test');
await sbx.kill();