Skip to content
View as Markdown

errors

Section titled “errors”
import "github.com/daytona/clients/sdk-go/pkg/errors"

Package errors defines the typed error model used by the Daytona Go SDK.

Every error returned by the SDK is a `*DaytonaError` carrying a human-readable message, the HTTP `StatusCode` (when applicable), an optional machine-readable `Code` / `Source` pair, and the response `Headers`. There are no per-status struct types — a single concrete type keeps the surface small and unambiguous.

Branching is done with `errors.Is` against the package-level sentinels:

if errors.Is(err, sdkerrors.ErrNotFound) {
    // any HTTP 404 from any source
}
if errors.Is(err, sdkerrors.ErrGitAuthFailed) {
    // precisely DAYTONA_DAEMON / GIT_AUTH_FAILED
}
if errors.Is(err, sdkerrors.ErrAuthentication) {
    // the same git-auth error ALSO matches the broader 401 sentinel,
    // mirroring the inheritance hierarchy of the other Daytona SDKs.
}

Reading metadata off an error is done with `errors.As`:

var de *sdkerrors.DaytonaError
if errors.As(err, &de) {
    log.Printf("status=%d code=%s source=%s", de.StatusCode, de.Code, de.Source)
}

When an SDK error was caused by an underlying Go error — most usefully a transport failure with no HTTP response (connection reset, timeout, dropped stream) — that error is kept in `Err` and exposed through `Unwrap`, so the standard matchers see through the `*DaytonaError`. Whether such a failure is worth retrying is the caller’s decision; retry only operations that are safe to repeat:

var netErr net.Error
if errors.Is(err, context.DeadlineExceeded) || (errors.As(err, &netErr) && netErr.Timeout()) {
    // transport timeout: retry if the operation is idempotent
}

Index

Section titled “Index”

Constants

Section titled “Constants”
const (
    SourceAPI    = "DAYTONA_API"
    SourceDaemon = "DAYTONA_DAEMON"
    SourceProxy  = "DAYTONA_PROXY"
    // SourceSDK is stamped on errors synthesized by the SDK itself and never appears on the wire.
    SourceSDK = "DAYTONA_SDK"
)

Variables

Section titled “Variables”
var (
    // HTTP status-class sentinels. Names follow HTTP terminology.
    ErrBadRequest          = &DaytonaError{StatusCode: http.StatusBadRequest}
    ErrAuthentication      = &DaytonaError{StatusCode: http.StatusUnauthorized}
    ErrForbidden           = &DaytonaError{StatusCode: http.StatusForbidden}
    ErrNotFound            = &DaytonaError{StatusCode: http.StatusNotFound}
    ErrTimeout             = &DaytonaError{StatusCode: http.StatusRequestTimeout}
    ErrConflict            = &DaytonaError{StatusCode: http.StatusConflict}
    ErrGone                = &DaytonaError{StatusCode: http.StatusGone}
    ErrUnprocessableEntity = &DaytonaError{StatusCode: http.StatusUnprocessableEntity}
    ErrRateLimit           = &DaytonaError{StatusCode: http.StatusTooManyRequests}
    ErrInternalServer      = &DaytonaError{StatusCode: http.StatusInternalServerError}
    ErrBadGateway          = &DaytonaError{StatusCode: http.StatusBadGateway}
    ErrServiceUnavailable  = &DaytonaError{StatusCode: http.StatusServiceUnavailable}
    ErrGatewayTimeout      = &DaytonaError{StatusCode: http.StatusGatewayTimeout}


    // Deprecated: use ErrBadRequest. Kept so existing callers do not break.
    ErrValidation = ErrBadRequest
    // Deprecated: use ErrForbidden. Kept so existing callers do not break.
    ErrAuthorization = ErrForbidden


    // SDK-detected sandbox lifecycle.
    ErrQueueTimeout = &DaytonaError{StatusCode: http.StatusRequestTimeout, Source: SourceSDK, Code: "SANDBOX_QUEUE_TIMEOUT"}
    ErrSpotEvicted  = &DaytonaError{Source: SourceSDK, Code: "SANDBOX_SPOT_EVICTED"}


    // Daemon: git.
    ErrGitAuthFailed     = &DaytonaError{Source: SourceDaemon, Code: "GIT_AUTH_FAILED"}
    ErrGitRepoNotFound   = &DaytonaError{Source: SourceDaemon, Code: "GIT_REPO_NOT_FOUND"}
    ErrGitBranchNotFound = &DaytonaError{Source: SourceDaemon, Code: "GIT_BRANCH_NOT_FOUND"}
    ErrGitBranchExists   = &DaytonaError{Source: SourceDaemon, Code: "GIT_BRANCH_EXISTS"}
    ErrGitPushRejected   = &DaytonaError{Source: SourceDaemon, Code: "GIT_PUSH_REJECTED"}
    ErrGitDirtyWorktree  = &DaytonaError{Source: SourceDaemon, Code: "GIT_DIRTY_WORKTREE"}
    ErrGitMergeConflict  = &DaytonaError{Source: SourceDaemon, Code: "GIT_MERGE_CONFLICT"}
    // ErrGitTransportFailed matches network-level git failures: DNS, TLS,
    // connection, timeout.
    ErrGitTransportFailed = &DaytonaError{Source: SourceDaemon, Code: "GIT_TRANSPORT_FAILED"}
    // ErrGitRemoteRejected matches server-side rejections: pre-receive/update
    // hooks, branch protection, size/quota limits.
    ErrGitRemoteRejected = &DaytonaError{Source: SourceDaemon, Code: "GIT_REMOTE_REJECTED"}


    // Daemon: filesystem.
    ErrFileNotFound     = &DaytonaError{Source: SourceDaemon, Code: "FILE_NOT_FOUND"}
    ErrFileAccessDenied = &DaytonaError{Source: SourceDaemon, Code: "FILE_ACCESS_DENIED"}
    // ErrInvalidFilePath matches DAYTONA_DAEMON / INVALID_FILE_PATH (HTTP 400).
    ErrInvalidFilePath = &DaytonaError{Source: SourceDaemon, Code: "INVALID_FILE_PATH"}
    // ErrFileReadFailed matches DAYTONA_DAEMON / FILE_READ_FAILED (HTTP 500).
    ErrFileReadFailed = &DaytonaError{Source: SourceDaemon, Code: "FILE_READ_FAILED"}


    // Daemon: LSP.
    ErrLspServerNotInitialized = &DaytonaError{Source: SourceDaemon, Code: "LSP_SERVER_NOT_INITIALIZED"}


    // Daemon: process / session.
    ErrProcessExecutionTimeout = &DaytonaError{Source: SourceDaemon, Code: "PROCESS_EXECUTION_TIMEOUT"}
    ErrProcessNotFound         = &DaytonaError{Source: SourceDaemon, Code: "PROCESS_NOT_FOUND"}
    ErrSessionEnded            = &DaytonaError{Source: SourceDaemon, Code: "SESSION_ENDED"}
    ErrCommandAlreadyCompleted = &DaytonaError{Source: SourceDaemon, Code: "COMMAND_ALREADY_COMPLETED"}


    // Daemon: computer-use.
    ErrA11yUnavailable         = &DaytonaError{Source: SourceDaemon, Code: "A11Y_UNAVAILABLE"}
    ErrRecordingStillActive    = &DaytonaError{Source: SourceDaemon, Code: "RECORDING_STILL_ACTIVE"}
    ErrRecordingFfmpegNotFound = &DaytonaError{Source: SourceDaemon, Code: "RECORDING_FFMPEG_NOT_FOUND"}
)

func ConvertAPIError

Section titled “func ConvertAPIError”
func ConvertAPIError(err error, httpResp *http.Response) error

ConvertAPIError converts an error returned by the generated api-client-go (and an optional `*http.Response`) into a `*DaytonaError`.

func ConvertToolboxError

Section titled “func ConvertToolboxError”
func ConvertToolboxError(err error, httpResp *http.Response) error

ConvertToolboxError converts an error returned by the generated toolbox-api-client-go into a `*DaytonaError`.

type DaytonaAuthenticationError

Section titled “type DaytonaAuthenticationError”

Deprecated: match with `errors.Is(err, ErrAuthentication)` instead.

type DaytonaAuthenticationError struct{ *DaytonaError }

func NewDaytonaAuthenticationError

Section titled “func NewDaytonaAuthenticationError”
func NewDaytonaAuthenticationError(message string, headers http.Header) *DaytonaAuthenticationError

Deprecated: use NewDaytonaError(message, http.StatusUnauthorized, headers).

func (*DaytonaAuthenticationError) Unwrap

Section titled “func (*DaytonaAuthenticationError) Unwrap”
func (e *DaytonaAuthenticationError) Unwrap() error

type DaytonaConflictError

Section titled “type DaytonaConflictError”

Deprecated: match with `errors.Is(err, ErrConflict)` instead.

type DaytonaConflictError struct{ *DaytonaError }

func NewDaytonaConflictError

Section titled “func NewDaytonaConflictError”
func NewDaytonaConflictError(message string, headers http.Header) *DaytonaConflictError

Deprecated: use NewDaytonaError(message, http.StatusConflict, headers).

func (*DaytonaConflictError) Unwrap

Section titled “func (*DaytonaConflictError) Unwrap”
func (e *DaytonaConflictError) Unwrap() error

type DaytonaError

Section titled “type DaytonaError”

DaytonaError is the single error type returned by the SDK. Use `errors.As(err, &target *DaytonaError)` to read its fields and `errors.Is(err, sentinel)` to branch on the kind.

type DaytonaError struct {
    Message    string
    StatusCode int
    Code       string
    Source     string
    Headers    http.Header
    // Err is the underlying error, if any (for example the *url.Error of a
    // request that never got a response). It is returned by Unwrap and is
    // not part of Error() and is not serialized to JSON.
    Err error `json:"-"`
}

func NewDaytonaConnectionError

Section titled “func NewDaytonaConnectionError”
func NewDaytonaConnectionError(message string) *DaytonaError

NewDaytonaConnectionError is a convenience constructor for transport-level failures with no HTTP response (DNS, dial, TLS, mid-request drop).

func NewDaytonaError

Section titled “func NewDaytonaError”
func NewDaytonaError(message string, statusCode int, headers http.Header) *DaytonaError

NewDaytonaError builds a DaytonaError with the given message, status code and headers. `Source` is left empty for SDK-internal errors unless the translation layer populates it from a server-side envelope. Most callers should use this directly; the sentinels below are for branching with `errors.Is`, not for constructing errors.

func NewDaytonaErrorFromBody

Section titled “func NewDaytonaErrorFromBody”
func NewDaytonaErrorFromBody(body []byte, statusCode int, headers http.Header) *DaytonaError

NewDaytonaErrorFromBody parses a JSON response body and builds a DaytonaError. When the body carries its own `statusCode` field that overrides the caller-supplied one (server-side envelopes are authoritative).

func NewDaytonaTimeoutError

Section titled “func NewDaytonaTimeoutError”
func NewDaytonaTimeoutError(message string) *DaytonaError

NewDaytonaTimeoutError is a convenience constructor for client-side timeouts. Equivalent to `NewDaytonaError(message, http.StatusRequestTimeout, nil)`.

func NewDaytonaValidationError

Section titled “func NewDaytonaValidationError”
func NewDaytonaValidationError(message string, headers http.Header) *DaytonaError

Deprecated: use NewDaytonaError(message, http.StatusBadRequest, headers).

func NewQueueTimeoutError

Section titled “func NewQueueTimeoutError”
func NewQueueTimeoutError(message string) *DaytonaError

NewQueueTimeoutError is a convenience constructor for SDK-detected sandbox queue timeout destruction. It matches both ErrQueueTimeout and ErrTimeout.

func NewSpotEvictedError

Section titled “func NewSpotEvictedError”
func NewSpotEvictedError(message string) *DaytonaError

NewSpotEvictedError is a convenience constructor for SDK-detected spot preemption destruction.

func WrapDaytonaError

Section titled “func WrapDaytonaError”
func WrapDaytonaError(err error, message string, statusCode int, headers http.Header) *DaytonaError

WrapDaytonaError builds a DaytonaError like NewDaytonaError and keeps err as its cause, reachable through Unwrap. The message is used verbatim; err is not appended to it.

func (*DaytonaError) As

Section titled “func (*DaytonaError) As”
func (e *DaytonaError) As(target any) bool

As lets `errors.As` populate the deprecated typed errors with their original status-code semantics, even though the SDK only produces *DaytonaError. Runs only after the stdlib’s direct assignability check, so `errors.As(err, &de)` with a *DaytonaError target is unaffected.

func (*DaytonaError) Error

Section titled “func (*DaytonaError) Error”
func (e *DaytonaError) Error() string

func (*DaytonaError) Is

Section titled “func (*DaytonaError) Is”
func (e *DaytonaError) Is(target error) bool

Is implements the `errors.Is` contract. A target matches when it is one of the package-level sentinels and either:

  • the target carries a non-empty `Code`, in which case BOTH `Source` and `Code` must match exactly (domain-code sentinel), or
  • the target carries a non-zero `StatusCode`, in which case the receiver’s `StatusCode` must match (status-class sentinel).

Because the SDK always stamps the HTTP status alongside the domain code, `errors.Is(err, ErrGitAuthFailed)` and `errors.Is(err, ErrAuthentication)` both match the same underlying error — mirroring the inheritance hierarchy used by the Python/TypeScript/Java SDKs.

func (*DaytonaError) Unwrap

Section titled “func (*DaytonaError) Unwrap”
func (e *DaytonaError) Unwrap() error

Unwrap returns the underlying error, so `errors.Is` / `errors.As` can match the cause (for example `context.DeadlineExceeded`, `io.ErrUnexpectedEOF`, `syscall.ECONNRESET`, or a `net.Error`). It returns nil when the error has no cause.

type DaytonaForbiddenError

Section titled “type DaytonaForbiddenError”

Deprecated: match with `errors.Is(err, ErrForbidden)` instead.

type DaytonaForbiddenError struct{ *DaytonaError }

func NewDaytonaForbiddenError

Section titled “func NewDaytonaForbiddenError”
func NewDaytonaForbiddenError(message string, headers http.Header) *DaytonaForbiddenError

Deprecated: use NewDaytonaError(message, http.StatusForbidden, headers).

func (*DaytonaForbiddenError) Unwrap

Section titled “func (*DaytonaForbiddenError) Unwrap”
func (e *DaytonaForbiddenError) Unwrap() error

type DaytonaNotFoundError

Section titled “type DaytonaNotFoundError”

Deprecated: match with `errors.Is(err, ErrNotFound)` instead.

type DaytonaNotFoundError struct{ *DaytonaError }

func NewDaytonaNotFoundError

Section titled “func NewDaytonaNotFoundError”
func NewDaytonaNotFoundError(message string, headers http.Header) *DaytonaNotFoundError

Deprecated: use NewDaytonaError(message, http.StatusNotFound, headers).

func (*DaytonaNotFoundError) Unwrap

Section titled “func (*DaytonaNotFoundError) Unwrap”
func (e *DaytonaNotFoundError) Unwrap() error

type DaytonaRateLimitError

Section titled “type DaytonaRateLimitError”

Deprecated: match with `errors.Is(err, ErrRateLimit)` instead.

type DaytonaRateLimitError struct{ *DaytonaError }

func NewDaytonaRateLimitError

Section titled “func NewDaytonaRateLimitError”
func NewDaytonaRateLimitError(message string, headers http.Header) *DaytonaRateLimitError

Deprecated: use NewDaytonaError(message, http.StatusTooManyRequests, headers).

func (*DaytonaRateLimitError) Unwrap

Section titled “func (*DaytonaRateLimitError) Unwrap”
func (e *DaytonaRateLimitError) Unwrap() error

type DaytonaServerError

Section titled “type DaytonaServerError”

Deprecated: match with `errors.Is(err, ErrInternalServer)` or compare StatusCode >= 500 on *DaytonaError instead.

type DaytonaServerError struct{ *DaytonaError }

func NewDaytonaServerError

Section titled “func NewDaytonaServerError”
func NewDaytonaServerError(message string, statusCode int, headers http.Header) *DaytonaServerError

Deprecated: use NewDaytonaError(message, statusCode, headers).

func (*DaytonaServerError) Unwrap

Section titled “func (*DaytonaServerError) Unwrap”
func (e *DaytonaServerError) Unwrap() error

type DaytonaTimeoutError

Section titled “type DaytonaTimeoutError”

Deprecated: match with `errors.Is(err, ErrTimeout)` or `errors.Is(err, ErrGatewayTimeout)` instead.

type DaytonaTimeoutError struct{ *DaytonaError }

func (*DaytonaTimeoutError) Unwrap

Section titled “func (*DaytonaTimeoutError) Unwrap”
func (e *DaytonaTimeoutError) Unwrap() error

type DaytonaValidationError

Section titled “type DaytonaValidationError”

Deprecated: match with `errors.Is(err, ErrBadRequest)` instead.

type DaytonaValidationError struct{ *DaytonaError }

func (*DaytonaValidationError) Unwrap

Section titled “func (*DaytonaValidationError) Unwrap”
func (e *DaytonaValidationError) Unwrap() error