Errors

Match an error with errors.Is or errors.As. The sentinel is the stable part. The text can change.

Setup

You observe	Sentinel or cause	What to do
New returns an error about MaxConns	The pool is smaller than the completion slots plus 6.	Raise MaxConns, or lower WithWorkers or WithTxSlots.
New returns an error about isolation	The pool default is not READ COMMITTED.	Set default_transaction_isolation=read committed on the pool.
Start returns ErrProducerOnly	The client has no handlers.	Register handlers on the worker. Use this client only to submit work.

Migrate is safe to call at each process start. A second call applies only a pending migration.

Submit and enqueue

You observe	Sentinel	Meaning
errors.As yields *DuplicateError	ErrDuplicate	An active run already holds this unique key. RunID on the error is that run.
errors.As yields *SubmitConflictError	ErrSubmitConflict	This submit-once key already belongs to a run with a different input.
errors.As yields *PayloadTooLargeError	ErrPayloadTooLarge	The encoded input or output is over the limit.
A builder returns several errors	The error from Submit	Submit reports every builder error. The run is not inserted.

A method that ends in Tx inserts the run in your transaction. The run is visible after you commit. Wait after the commit. For a wakeup at commit, use TrackWakeups and call PublishWakeups after the commit.

Wait for a run

You observe	Sentinel	Meaning
Result or Output fails	ErrRunNotCompleted	The run is failed or cancelled.
Output fails	ErrNotCompleted	That node is not complete yet.
Output fails	ErrNoOutput	The node completed and stored no output. A run from Define has no result node.
Open on a definition fails	ErrRunMismatch	The stored run is a different workflow, kind, or kind version.
Any read fails	ErrRunNotFound	No row has this run ID.

Wait returns the terminal status. A failed run is not an error from Wait. Read State.

A cancel of the context that you give to Result or Wait returns the context error. The run continues.

Control a run

Call	Sentinel	When
Cancel, Signal, Pause	ErrAlreadyTerminal	The run is already terminal. The CLI cancel command exits 0 in this case.
Pause	ErrAlreadyPaused	The run is already paused.
Resume	ErrNotPaused	The run is not paused.
Signal	ErrSignalNotDeclared	This run has no wait for that signal name.
Retry	ErrNotFailed	The run is not failed.
Retry	ErrNoExhaustedNode	That node is not an exhausted step.
Retry	ErrChildNotRetryable	The child run cannot start again.
PauseSchedule and ResumeSchedule	ErrScheduleNotFound	No schedule has this ID. Unschedule is PauseSchedule.

WithErrorHandler receives ErrRunDeadlineExceeded when a run deadline discards a step. It receives ErrReclaimLimitExceeded when a step passes WithMaxReclaims.

Next

• Payload limits
• Unique jobs
• Submit once
• States