Errors

Last updated 2026-10-02

This page lists every error message go-queue returns or logs, what triggers it, and how to match it.

Error Messages

Source	Message	Trigger
`Start`	`queue already started`	Already Running
`Start`	`queue already closed`	Already Closed
`Enqueue`	`ctx.Err()` as-is	The passed ctx is cancelled or expired
`Enqueue`	`enqueue failed: staging queue is full`	Heap length reached `Config.Size`
`Enqueue`	`enqueue failed: staging queue is closed`	`Shutdown` was called
`Shutdown`	`shutdown timeout: N tasks remaining`	`ctx` expired before the heap drained
Task (logged)	`task timeout after <d>`	Task exceeded its timeout
Task (logged)	`panic: <value>`	Task function panicked

Matching Errors

ctx errors from Enqueue are returned unwrapped, so errors.Is(err, context.Canceled) and errors.Is(err, context.DeadlineExceeded) work. The full / closed errors have no exported sentinel and can only be matched by message:

if _, err := q.Enqueue(ctx, "email", sendEmail); err != nil {
    switch {
    case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):
        // caller gave up
    case strings.Contains(err.Error(), "staging queue is full"):
        // back off and retry later
    case strings.Contains(err.Error(), "staging queue is closed"):
        // queue is shutting down
    }
}

Task-side errors never return to the caller; they appear in Log Events.