Errors

Import ErrorCode and RunlaneError from @runlane/core.

Construct an error

Use RunlaneError when a task needs to state whether a failure can be retried:

import { ErrorCode, RunlaneError } from '@runlane/core'

throw new RunlaneError({
  code: ErrorCode.TaskFailed,
  message: 'The account no longer exists.',
  retryable: false,
  meta: { reason: 'account_deleted' },
})

The constructor accepts RunlaneErrorOptions:

Field	Type and default
`code`	Required `ErrorCode`.
`message`	Optional string. Defaults to the code.
`retryable`	Optional boolean. Defaults to `false`.
`cause`	Optional original thrown value, kept for internal diagnosis.
`meta`	Optional `JsonObject` with safe, structured context.

The instance extends Error and exposes these fields. Use error instanceof RunlaneError before reading them. Match error.code, not message text. If you catch another kind of error, treat it as an unexpected application or dependency failure.

Thrown errors and stored failures

Public operations such as trigger() reject when setup, validation, storage, or delivery fails. Catch those errors around the API call.

Handler failures are normally saved on the run. runNow() executes one attempt and returns a RunRecord; a failed handler does not normally make that call reject. Check the returned run's status and failure, or read the run later through runlane.runs.get().

A stored RunFailure has code, message, retryable, and optional meta. Runlane uses a stable public message for the code. It does not store the original stack, cause, or custom error message in that failure record. Put safe details needed by operators in meta; keep secrets and raw provider responses out of it.

Retry decisions

Handler result	Automatic retry behavior
Ordinary thrown `Error`, with a task retry policy	Retryable while the attempt count is below `maxAttempts`.
`RunlaneError` with `retryable: true`	Retryable only if the task also has a retry policy and budget remains.
`RunlaneError` with `retryable: false` or no `retryable` field	Ends as `failed` without automatic retry.
Any failure with no task retry policy	No automatic retry.
Attempt deadline expires	Records `TaskTimedOut`. Retries if the task policy allows another attempt; otherwise ends as `failed`.
Returned release or wait	Ends the attempt without recording a failure. Resumed attempts still count toward later retry decisions.

Mark a failure retryable only if repeating the work can help. The retry guide shows both temporary and permanent failures in one task.

Error codes

These members belong to ErrorCode. Their stored values use snake case.

Member	Stored value	Meaning
`AdapterContractViolation`	`adapter_contract_violation`	An adapter returned data or behavior outside its contract.
`CapabilityUnsupported`	`capability_unsupported`	The configured lane or provider does not support the operation.
`ConfigurationInvalid`	`configuration_invalid`	A definition or option is invalid.
`InternalError`	`internal_error`	An internal operation failed.
`InvariantViolation`	`invariant_violation`	Stored or runtime state violates a required rule.
`OperationCancelled`	`operation_cancelled`	An operation was cancelled.
`ObservationExportFailed`	`observation_export_failed`	Exporting observations failed.
`RunNotFound`	`run_not_found`	An operation requires a run that does not exist. A plain `runs.get()` returns `undefined` instead.
`ScheduleNotFound`	`schedule_not_found`	A required schedule was not found.
`StorageConflict`	`storage_conflict`	A concurrent write or ownership claim conflicted.
`StorageUnavailable`	`storage_unavailable`	Storage could not serve the operation.
`TaskFailed`	`task_failed`	The task handler failed.
`TaskNotFound`	`task_not_found`	The runtime cannot find the task definition.
`TaskOutputInvalid`	`task_output_invalid`	Task output does not match its schema or storage format.
`TaskTimedOut`	`task_timed_out`	The attempt exceeded its time limit.
`TransportPublishFailed`	`transport_publish_failed`	Publishing a delivery request failed.
`TransportUnavailable`	`transport_unavailable`	The delivery service is unavailable.
`ValidationFailed`	`validation_failed`	A payload or other operation input failed validation.
`WaitTokenNotFound`	`wait_token_not_found`	An operation requires a missing wait token. A plain token read returns `undefined` instead.
`WaitTokenOutputInvalid`	`wait_token_output_invalid`	A completed token's output does not match the requested schema.

Use the error's retryable field and the operation's state to decide what to do next. An error code alone is not a promise that retrying is safe.

Construct an error

Thrown errors and stored failures

Retry decisions

Error codes

On this page