Errors

DaytonaError

Properties:

statusCode? number
code? ErrorCode | string
source? string
traceId? string
retryAfterSecs? number
flag? string
workloadApiUrl? string
centralApiUrl? string
invocationId? string
replacement? string
firstAvailableCursor? string
stated? string
actual? string
region? string
errorCode? string
requestId? string
retryAfterMs? number

Constructors

Constructor

new DaytonaError(
   message: string,
   statusCode?: number,
   code?: string,
   source?: string,
   envelope?: ErrorEnvelope): DaytonaError;

Parameters:

message string
statusCode? number
code? string
source? string
envelope? ErrorEnvelope

Returns:

DaytonaError

The connection failed while the create() request was in flight. Same outcome as SandboxCreateRequestTimeoutError: the sandbox may or may not exist; retry create() with the same idempotencyKey and create options, in the same project and coordinator or cell.

Properties:

idempotencyKey string

Constructors

Constructor

new SandboxCreateConnectionError(
   idempotencyKey: string,
   detail: string): SandboxCreateConnectionError;

Parameters:

idempotencyKey string
detail string

Returns:

SandboxCreateConnectionError

SandboxCreateRequestTimeoutError

The create() request itself timed out before the server answered. The server may still have created the sandbox. idempotencyKey is the key the request was sent with. Retry with that key and identical create options, in the same project and coordinator or cell, to recover the sandbox (or create it if the first request never landed). New records reject changed requests; historical mappings without a request digest may replay the original without detecting changes.

Properties:

idempotencyKey string

Constructors

Constructor

new SandboxCreateRequestTimeoutError(
   idempotencyKey: string): SandboxCreateRequestTimeoutError;

Parameters:

idempotencyKey string

Returns:

SandboxCreateRequestTimeoutError

SandboxCreateTimeoutError

create() ran out of caller budget while the sandbox was still starting. The sandbox was created and is left running; sandboxId lets the caller pick it up (daytona.sandbox(sandboxId)) or delete it.

Properties:

sandboxId string

Constructors

Constructor

new SandboxCreateTimeoutError(sandboxId: string): SandboxCreateTimeoutError;

Parameters:

sandboxId string

Returns:

SandboxCreateTimeoutError

SandboxTerminalStateError

waitForState() saw the sandbox reach a terminal state before any target. state is the observed public sandbox state (e.g. 'destroyed').

Properties:

state SandboxState
rawState? string

Constructors

Constructor

new SandboxTerminalStateError(
   sandboxId: string,
   state: SandboxState,
   rawState?: string): SandboxTerminalStateError;

Parameters:

sandboxId string
state SandboxState
rawState? string

Returns:

SandboxTerminalStateError

DockerNotReadyError

sandbox.docker.waitUntilReady() saw Docker Engine settle in a state that will not become ready in this boot (failed, not_present, disabled, unmanaged, unsupported, or deferred with reason function-ready-template). status is the observed Docker status; its reason says why, and processId (when set) names the process whose logs hold Docker's output. The sandbox itself stays usable.

Properties:

status DockerStatus

Constructors

Constructor

new DockerNotReadyError(status: DockerStatus): DockerNotReadyError;

Parameters:

status DockerStatus

Returns:

DockerNotReadyError

DockerWaitTimeoutError

sandbox.docker.waitUntilReady() ran out of caller budget before Docker Engine became ready. status is the last observed Docker status (starting, or deferred while the boot has not started Docker yet), or undefined when no status answer arrived before the deadline (for example a stalled first request).

Properties:

status? DockerStatus

Constructors

Constructor

new DockerWaitTimeoutError(status: DockerStatus | undefined): DockerWaitTimeoutError;

Parameters:

status DockerStatus | undefined

Returns:

DockerWaitTimeoutError

ConflictError

PreconditionFailedError

GoneError

PayloadTooLargeError

UnsupportedMediaTypeError

UnprocessableEntityError

MethodNotAllowedError

ServiceUnavailableError

InternalServerError

RateLimitError

LimitExceededError

LIMIT_EXCEEDED (429): an organization limit is exhausted. Subclasses RateLimitError, so catch/instanceof RateLimitError keeps matching; limit is the limit's stable machine name (e.g. max_concurrent_vms) and current/max are the counts the refusal was computed from. Fields are undefined when a body omits or malforms them.

Properties:

limit? string
current? number
max? number

Constructors

Constructor

new LimitExceededError(
   message: string,
   statusCode?: number,
   code?: string,
   source?: string,
   envelope?: ErrorEnvelope): LimitExceededError;

Parameters:

message string
statusCode? number
code? string
source? string
envelope? ErrorEnvelope

Returns:

LimitExceededError

PreconditionRequiredError

ConnectionError

TimeoutError

NotSupportedError

ProcessNotFoundError

ProcessStartFailedError

ProcessTerminalError

ProcessExecutionTimeoutError

NameConflictError

NotSupportedForClassError

OrgSuspendedError

ProjectBudgetExceededError

PROJECT_BUDGET_EXCEEDED (402): the project reached its monthly budget. New sandboxes cannot start in it until the budget is raised or removed, or the next calendar month (UTC) begins.

OriginImportOnlyError

OverloadedError

InvalidCursorError

CursorExpiredError

StdinClosedError

StdinUnavailableError

ProtectedProcessError

RateLimitedError

ReadOnlyUnsupportedError

UnsupportedOperationError

UnsupportedVolumeTypeError

SessionNotFoundError

SessionEndedError

SearchNotConfiguredError

SearchUnavailableError

SandboxNotRunningError

SandboxStartFailedError

SandboxWakingError

KernelUnavailableError

LspNotStartedError

LspServerUnavailableError

AddonUnavailableError

FileNotFoundError

InvalidFilePathError

FileAccessDeniedError

FileReadFailedError

AtomicUploadUnsupportedError

GitAuthFailedError

GitRepoNotFoundError

GitBranchNotFoundError

GitBranchExistsError

DesktopNotReadyError

FsFreezeUnsupportedError

FS_FREEZE_UNSUPPORTED: runner-only control route; the guest has no freezable scratch filesystem.

NoDefaultGatewayError

NO_DEFAULT_GATEWAY: runner-only control route; the guest has no usable default gateway yet. Retry.

ImageNotFoundError

ImageNotReadyError

ImageFormatOutdatedError

IMAGE_FORMAT_OUTDATED (409): the image is stored in an older format than the current one (Image.formatOutdated) and this door cannot convert it. Convert it with POST /images/{id}/convert, or create a Linux sandbox from it, which converts it first.

ImageBuildFailedError

Properties:

imageId? string
buildError string

Constructors

Constructor

new ImageBuildFailedError(
   message: string,
   statusCode?: number,
   code?: string,
   source?: string,
   envelope?: ErrorEnvelope,
   imageId?: string): ImageBuildFailedError;

Parameters:

message string
statusCode? number
code? string
source? string
envelope? ErrorEnvelope
imageId? string

Returns:

ImageBuildFailedError

ImageClassMismatchError

ImageNameTakenError

ImageNameReservedError

IdleOutOfRangeError

CreateTtlOutOfRangeError

SnapshotNotFoundError

SnapshotNotReadyError

SnapshotClassMismatchError

TransferCancelledError

Constructors

Constructor

new TransferCancelledError(message = 'file transfer cancelled'): TransferCancelledError;

Parameters:

message string = 'file transfer cancelled'

Returns:

TransferCancelledError

BuildLogInterruptedError

Last successfully delivered checkpoint. Callback failures never auto-retry.

Properties:

cause? unknown

Constructors

Constructor

new BuildLogInterruptedError(
   message: string,
   cursor?: string,
   code = 'BUILD_LOG_INTERRUPTED',
   statusCode?: number): BuildLogInterruptedError;

Parameters:

message string
cursor? string
code string = 'BUILD_LOG_INTERRUPTED'
statusCode? number

Returns:

BuildLogInterruptedError

isKnownErrorCode

function isKnownErrorCode(code: string | undefined): code is ErrorCode;

ApiErrorCode

type ApiErrorCode = (typeof API_ERROR_CODES)[number]

DaemonErrorCode

type DaemonErrorCode = (typeof DAEMON_ERROR_CODES)[number]

GenericErrorCode

type GenericErrorCode = (typeof GENERIC_ERROR_CODES)[number]

ProxyErrorCode

type ProxyErrorCode = (typeof PROXY_ERROR_CODES)[number]

RouterErrorCode

type RouterErrorCode = (typeof ROUTER_ERROR_CODES)[number]

ErrorCode

type ErrorCode = DaemonErrorCode | ApiErrorCode | ProxyErrorCode | RouterErrorCode | GenericErrorCode

API_ERROR_CODES

const API_ERROR_CODES = [
  'BILLING_DISABLED',
  'BILLING_UNREACHABLE',
  'BUCKET_CREATE_FAILED',
  'BUCKET_DELETE_FAILED',
  'BUCKET_NOT_EMPTY',
  'CREATE_BODY_TOO_LARGE',
  'CREATE_OPERATION_RETIRED',
  'CROSS_CELL_PLACEMENT_UNSUPPORTED',
  'ECR_ACCOUNT_MISMATCH',
  'ECR_CREDENTIALS_INVALID',
  'ECR_OWNERSHIP_UNVERIFIABLE',
  'ENTITLEMENT_REQUIRED',
  'FEATURE_FLAG_DISABLED',
  'HARDWARE_REPLY_TOO_LARGE',
  'INSTANCE_CREATE_FAILED',
  'INSTANCE_UNREACHABLE',
  'INVALID_FOR_SOURCE',
  'INVOCATION_TIMEOUT',
  'LIMIT_EXCEEDED',
  'IDENTITY_NOT_FOUND',
  'WORKOS_SYNC_DISABLED',
  'USAGE_UNAVAILABLE',
  'BAD_RANGE',
  'BAD_RESOLUTION',
  'BAD_RUNNER',
  'BILLING_FORBIDDEN',
  'BILLING_ERROR',
  'BUILD_LOG_BATCH_TOO_LARGE',
  'IF_MATCH_REQUIRED',
  'MANAGEMENT_PLANE_ELSEWHERE',
  'NETWORK_POLICY_DOMAINS_REQUIRE_BLOCK_ALL',
  'NETWORK_POLICY_TRANSITION_IN_PROGRESS',
  'STALE_NETWORK_POLICY_REVISION',
  'NOT_SUPPORTED_FOR_CLASS',
  'IMAGE_NOT_FOUND',
  'IMAGE_NOT_READY',
  'IMAGE_BUILD_FAILED',
  'IMAGE_FORMAT_OUTDATED',
  'IMAGE_CLASS_MISMATCH',
  'IMAGE_NAME_TAKEN',
  'IMAGE_NAME_RESERVED',
  'IDLE_OUT_OF_RANGE',
  'CREATE_TTL_OUT_OF_RANGE',
  'SNAPSHOT_NOT_FOUND',
  'SNAPSHOT_NOT_READY',
  'SNAPSHOT_CLASS_MISMATCH',
  'IMPORTED_KEY_ALWAYS_SYNCED',
  'KEY_SYNC_NOT_APPLICABLE',
  'ORG_SUSPENDED',
  'ORIGIN_IMPORT_ONLY',
  'OVERLOADED',
  'PLACEMENT_AUTHORITY_REQUIRED',
  'PLACEMENT_CONTEXT_TOO_LARGE',
  'PLACEMENT_RECEIPT_TOO_LARGE',
  'PLACEMENT_ROUTER_REQUIRED',
  'PLACEMENT_UNAVAILABLE',
  'PROJECT_BUDGET_EXCEEDED',
  'RATE_LIMITED',
  'READ_ONLY_UNSUPPORTED',
  'SEARCH_NOT_CONFIGURED',
  'SEARCH_UNAVAILABLE',
  'SOURCE_AMBIGUOUS',
  'TOPOLOGY_NOT_READY',
  'UNSUPPORTED_VOLUME_TYPE',
  'WORKLOAD_PLANE_ELSEWHERE',
  'NO_ACTIVE_RESERVATION',
  'NO_FREE_SLOT',
  'RESERVATION_NOT_FOUND',
  'NO_MAC_AVAILABLE',
  'AUTO_RESERVE_LIMIT_REACHED',
  'IDEMPOTENCY_KEY_REUSED',
  'INSUFFICIENT_BALANCE',
  'CHARGE_FAILED',
  'CHECKPOINT_PENDING',
  'NO_CHECKPOINT',
  'SECRETS_UNSUPPORTED_ON_MACOS',
  'CHECKPOINT_FAILED',
] as const

DAEMON_ERROR_CODES

const DAEMON_ERROR_CODES = [
  'PROCESS_NOT_FOUND',
  'PROCESS_START_FAILED',
  'PROCESS_TERMINAL',
  'PROCESS_EXECUTION_TIMEOUT',
  'NAME_CONFLICT',
  'INVALID_CURSOR',
  'CURSOR_EXPIRED',
  'STDIN_CLOSED',
  'STDIN_UNAVAILABLE',
  'PROTECTED_PROCESS',
  'UNSUPPORTED_OPERATION',
  'SESSION_NOT_FOUND',
  'SESSION_ENDED',
  'KERNEL_UNAVAILABLE',
  'LSP_SERVER_UNAVAILABLE',
  'LSP_NOT_STARTED',
  'ADDON_UNAVAILABLE',
  'FILE_NOT_FOUND',
  'INVALID_FILE_PATH',
  'FILE_ACCESS_DENIED',
  'FILE_READ_FAILED',
  'ATOMIC_UPLOAD_UNSUPPORTED',
  'GIT_AUTH_FAILED',
  'GIT_REPO_NOT_FOUND',
  'GIT_BRANCH_NOT_FOUND',
  'GIT_BRANCH_EXISTS',
  'DESKTOP_NOT_READY',
  'FS_FREEZE_UNSUPPORTED',
  'NO_DEFAULT_GATEWAY',
] as const

GENERIC_ERROR_CODES

const GENERIC_ERROR_CODES = [
  'BAD_GATEWAY',
  'BAD_REQUEST',
  'CONFLICT',
  'FORBIDDEN',
  'GATEWAY_TIMEOUT',
  'GONE',
  'INTERNAL_SERVER_ERROR',
  'METHOD_NOT_ALLOWED',
  'NOT_FOUND',
  'NOT_IMPLEMENTED',
  'PAYMENT_REQUIRED',
  'PAYLOAD_TOO_LARGE',
  'REQUEST_TIMEOUT',
  'SERVICE_UNAVAILABLE',
  'TOO_MANY_REQUESTS',
  'UNAUTHORIZED',
  'UNPROCESSABLE_ENTITY',
  'UNSUPPORTED_MEDIA_TYPE',
] as const

PROXY_ERROR_CODES

const PROXY_ERROR_CODES = [
  'SANDBOX_WAKING',
  'SANDBOX_NOT_RUNNING',
  'SANDBOX_START_FAILED',
] as const

ROUTER_ERROR_CODES

const ROUTER_ERROR_CODES = [
  'REGION_MISMATCH',
  'UNKNOWN_REGION',
  'REGION_REQUIRED',
  'RETIRED_REGION_SELECTOR',
  'IDEMPOTENCY_KEY_REQUIRED',
  'CREATE_BODY_TOO_LARGE',
  'PLACEMENT_UNAVAILABLE',
  'TOPOLOGY_NOT_READY',
] as const

CODE_STATUS

const CODE_STATUS: Record<ErrorCode, number> = {
  PROCESS_NOT_FOUND: 404,
  PROCESS_START_FAILED: 400,
  PROCESS_TERMINAL: 409,
  PROCESS_EXECUTION_TIMEOUT: 408,
  NAME_CONFLICT: 409,
  INVALID_CURSOR: 400,
  CURSOR_EXPIRED: 409,
  STDIN_CLOSED: 409,
  STDIN_UNAVAILABLE: 409,
  PROTECTED_PROCESS: 403,
  UNSUPPORTED_OPERATION: 400,
  SESSION_NOT_FOUND: 404,
  SESSION_ENDED: 410,
  KERNEL_UNAVAILABLE: 503,
  LSP_SERVER_UNAVAILABLE: 503,
  LSP_NOT_STARTED: 409,
  ADDON_UNAVAILABLE: 503,
  FILE_NOT_FOUND: 404,
  INVALID_FILE_PATH: 400,
  FILE_ACCESS_DENIED: 403,
  FILE_READ_FAILED: 500,
  ATOMIC_UPLOAD_UNSUPPORTED: 409,
  GIT_AUTH_FAILED: 401,
  GIT_REPO_NOT_FOUND: 404,
  GIT_BRANCH_NOT_FOUND: 404,
  GIT_BRANCH_EXISTS: 409,
  DESKTOP_NOT_READY: 409,
  FS_FREEZE_UNSUPPORTED: 409,
  NO_DEFAULT_GATEWAY: 503,
  BILLING_DISABLED: 501,
  BILLING_UNREACHABLE: 502,
  BUCKET_CREATE_FAILED: 502,
  BUCKET_DELETE_FAILED: 502,
  BUCKET_NOT_EMPTY: 409,
  CREATE_BODY_TOO_LARGE: 413,
  CREATE_OPERATION_RETIRED: 410,
  CROSS_CELL_PLACEMENT_UNSUPPORTED: 409,
  ECR_ACCOUNT_MISMATCH: 400,
  ECR_CREDENTIALS_INVALID: 400,
  ECR_OWNERSHIP_UNVERIFIABLE: 502,
  ENTITLEMENT_REQUIRED: 403,
  FEATURE_FLAG_DISABLED: 403,
  HARDWARE_REPLY_TOO_LARGE: 503,
  INSTANCE_CREATE_FAILED: 503,
  INSTANCE_UNREACHABLE: 502,
  INVALID_FOR_SOURCE: 400,
  INVOCATION_TIMEOUT: 504,
  LIMIT_EXCEEDED: 429,
  IDENTITY_NOT_FOUND: 404,
  WORKOS_SYNC_DISABLED: 402,
  USAGE_UNAVAILABLE: 503,
  BAD_RANGE: 400,
  BAD_RESOLUTION: 400,
  BAD_RUNNER: 400,
  BILLING_FORBIDDEN: 502,
  BILLING_ERROR: 502,
  BUILD_LOG_BATCH_TOO_LARGE: 413,
  IF_MATCH_REQUIRED: 428,
  MANAGEMENT_PLANE_ELSEWHERE: 501,
  NETWORK_POLICY_DOMAINS_REQUIRE_BLOCK_ALL: 400,
  NETWORK_POLICY_TRANSITION_IN_PROGRESS: 409,
  STALE_NETWORK_POLICY_REVISION: 412,
  NOT_SUPPORTED_FOR_CLASS: 409,
  IMAGE_NOT_FOUND: 404,
  IMAGE_NOT_READY: 409,
  IMAGE_BUILD_FAILED: 409,
  IMAGE_FORMAT_OUTDATED: 409,
  IMAGE_CLASS_MISMATCH: 409,
  IMAGE_NAME_TAKEN: 409,
  IMAGE_NAME_RESERVED: 400,
  IDLE_OUT_OF_RANGE: 400,
  CREATE_TTL_OUT_OF_RANGE: 400,
  SNAPSHOT_NOT_FOUND: 404,
  SNAPSHOT_NOT_READY: 409,
  SNAPSHOT_CLASS_MISMATCH: 409,
  IMPORTED_KEY_ALWAYS_SYNCED: 409,
  KEY_SYNC_NOT_APPLICABLE: 409,
  ORG_SUSPENDED: 402,
  ORIGIN_IMPORT_ONLY: 400,
  OVERLOADED: 429,
  PLACEMENT_AUTHORITY_REQUIRED: 501,
  PLACEMENT_CONTEXT_TOO_LARGE: 413,
  PLACEMENT_RECEIPT_TOO_LARGE: 413,
  PLACEMENT_ROUTER_REQUIRED: 409,
  PLACEMENT_UNAVAILABLE: 503,
  PROJECT_BUDGET_EXCEEDED: 402,
  RATE_LIMITED: 429,
  READ_ONLY_UNSUPPORTED: 400,
  SEARCH_NOT_CONFIGURED: 501,
  SEARCH_UNAVAILABLE: 503,
  SOURCE_AMBIGUOUS: 409,
  TOPOLOGY_NOT_READY: 503,
  UNSUPPORTED_VOLUME_TYPE: 400,
  WORKLOAD_PLANE_ELSEWHERE: 501,
  NO_ACTIVE_RESERVATION: 409,
  NO_FREE_SLOT: 409,
  RESERVATION_NOT_FOUND: 404,
  NO_MAC_AVAILABLE: 409,
  AUTO_RESERVE_LIMIT_REACHED: 409,
  IDEMPOTENCY_KEY_REUSED: 409,
  INSUFFICIENT_BALANCE: 402,
  CHARGE_FAILED: 402,
  CHECKPOINT_PENDING: 409,
  NO_CHECKPOINT: 409,
  SECRETS_UNSUPPORTED_ON_MACOS: 400,
  CHECKPOINT_FAILED: 409,
  SANDBOX_WAKING: 503,
  SANDBOX_NOT_RUNNING: 409,
  SANDBOX_START_FAILED: 409,
  REGION_MISMATCH: 400,
  UNKNOWN_REGION: 400,
  REGION_REQUIRED: 400,
  RETIRED_REGION_SELECTOR: 400,
  IDEMPOTENCY_KEY_REQUIRED: 400,
  BAD_GATEWAY: 502,
  BAD_REQUEST: 400,
  CONFLICT: 409,
  FORBIDDEN: 403,
  GATEWAY_TIMEOUT: 504,
  GONE: 410,
  INTERNAL_SERVER_ERROR: 500,
  METHOD_NOT_ALLOWED: 405,
  NOT_FOUND: 404,
  NOT_IMPLEMENTED: 501,
  PAYMENT_REQUIRED: 402,
  PAYLOAD_TOO_LARGE: 413,
  REQUEST_TIMEOUT: 408,
  SERVICE_UNAVAILABLE: 503,
  TOO_MANY_REQUESTS: 429,
  UNAUTHORIZED: 401,
  UNPROCESSABLE_ENTITY: 422,
  UNSUPPORTED_MEDIA_TYPE: 415,
}

API_CODE_EXTRAS

const API_CODE_EXTRAS: Partial<Record<ErrorCode, readonly string[]>> = {
  ENTITLEMENT_REQUIRED: ['entitlement'],
  FEATURE_FLAG_DISABLED: ['flag'],
  GONE: ['replacement'],
  INSTANCE_CREATE_FAILED: ['invocation_id'],
  INSTANCE_UNREACHABLE: ['invocation_id'],
  INVOCATION_TIMEOUT: ['invocation_id'],
  LIMIT_EXCEEDED: ['limit', 'current', 'max'],
  IDLE_OUT_OF_RANGE: ['max'],
  CREATE_TTL_OUT_OF_RANGE: ['max'],
  MANAGEMENT_PLANE_ELSEWHERE: ['central_api_url'],
  OVERLOADED: ['retry_after_secs', 'invocation_id'],
  RATE_LIMITED: ['retry_after_secs'],
  WORKLOAD_PLANE_ELSEWHERE: ['workload_api_url'],
}

The optional top-level envelope fields a code may carry beyond {code, message, source, trace_id} — the per-code extras arrays the contract artifacts publish. Extras are documented per SOURCE (the api's GONE carries replacement; the daemon's carries nothing), so there is one map per source; an unlisted code carries none.

DAEMON_CODE_EXTRAS

const DAEMON_CODE_EXTRAS: Partial<Record<ErrorCode, readonly string[]>> = {
  CURSOR_EXPIRED: ['firstAvailableCursor'],
}

PROXY_CODE_EXTRAS

const PROXY_CODE_EXTRAS: Partial<Record<ErrorCode, readonly string[]>> = {}

ROUTER_CODE_EXTRAS

const ROUTER_CODE_EXTRAS: Partial<Record<ErrorCode, readonly string[]>> = {
  REGION_MISMATCH: ['stated', 'actual'],
  UNKNOWN_REGION: ['region'],
}

DaytonaNotFoundError

const DaytonaNotFoundError = NotFoundError

DaytonaAuthenticationError

const DaytonaAuthenticationError = AuthenticationError

DaytonaAuthorizationError

const DaytonaAuthorizationError = AuthorizationError

DaytonaConflictError

const DaytonaConflictError = ConflictError

DaytonaValidationError

const DaytonaValidationError = BadRequestError

DaytonaRateLimitError

const DaytonaRateLimitError = RateLimitError

DaytonaTimeoutError

const DaytonaTimeoutError = TimeoutError

DaytonaConnectionError

const DaytonaConnectionError = ConnectionError

DaytonaNotSupportedError

const DaytonaNotSupportedError = NotSupportedError

On this page

Computersfor Agents