錯誤

最後更新 2026-10-21

本頁列出 go-queue 回傳或記錄的所有錯誤訊息、觸發條件，以及比對方式。

錯誤訊息

來源	訊息	觸發條件
`Start`	`queue already started`	已在 Running
`Start`	`queue already closed`	已 Closed
`Enqueue`	原樣回傳 `ctx.Err()`	傳入的 ctx 已取消或到期
`Enqueue`	`enqueue failed: staging queue is full`	堆長度達到 `Config.Size`
`Enqueue`	`enqueue failed: staging queue is closed`	已呼叫 `Shutdown`
`Shutdown`	`shutdown timeout: N tasks remaining`	堆排空前 `ctx` 到期
任務（僅記錄）	`task timeout after <d>`	任務超過逾時
任務（僅記錄）	`panic: <value>`	任務函式 panic
任務（僅記錄）	`context canceled`	`Start` 的 ctx 被取消，或 `Shutdown` 期限到時任務仍在執行或排隊中

比對錯誤

Enqueue 的 ctx 錯誤不經包裝直接回傳，因此 errors.Is(err, context.Canceled) 與 errors.Is(err, context.DeadlineExceeded) 可用。佇列已滿／已關閉的錯誤沒有公開 sentinel，只能比對訊息：

if _, err := q.Enqueue(ctx, "email", sendEmail); err != nil {
	switch {
	case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):
		// 呼叫端放棄
	case strings.Contains(err.Error(), "staging queue is full"):
		// 退避後再試
	case strings.Contains(err.Error(), "staging queue is closed"):
		// 佇列正在關閉
	}
}

任務端的錯誤不會回到呼叫端，只會出現在日誌事件。