hibiken/asynq · error

task not found

Error message

task not found

What it means

ErrTaskNotFound indicates the specified task cannot be found in the queue. Inspector task operations (GetTaskInfo, DeleteTask, RunTask, ArchiveTask, UpdateTaskPayload) map the internal not-found error to this sentinel when the task ID doesn't match any task in the given queue/state.

Solutions

1. Verify the task ID and queue name; list tasks (e.g. ListPendingTasks) to confirm it exists.
2. Set asynq.Retention on enqueue so completed tasks remain inspectable for a while.
3. Handle errors.Is(err, asynq.ErrTaskNotFound) as expected when tasks may have already completed.
4. Point the Inspector at the same Redis instance that served the task.

Example fix

// before
info, err := insp.GetTaskInfo("default", id)
if err != nil { return err }
// after
info, err := insp.GetTaskInfo("default", id)
if errors.Is(err, asynq.ErrTaskNotFound) {
    return nil // task already done
} else if err != nil {
    return err
}

// Check task still exists before acting:
if _, err := insp.GetTaskInfo(q, id); errors.Is(err, asynq.ErrTaskNotFound) { return ErrTaskGone }

func isTaskNotFound(err error) bool { return errors.Is(err, asynq.ErrTaskNotFound) }

if err := insp.DeleteTask(q, id); err != nil {
    if isTaskNotFound(err) { return nil }
    return err
}

When it happens

Trigger: inspector.GetTaskInfo(q, id) for an ID that never existed; the task already completed and passed its retention window; the task moved between states/queues; calling from a different Redis DB than the one that holds the task.

Common situations: Acting on a task ID stored before the task expired; race where the task finishes between lookup and action; retention not configured so completed tasks vanish immediately; inspecting the wrong queue name.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• queue not found
• queue is not empty
• asynq
• task already exists
• task ID conflicts with another task

AI-assisted analysis of hibiken/asynq@d135f1439b (2026-09-07). Data as JSON: /api/errors/c04e1af4e9ac820f. Report an issue: GitHub.

Appendix: source

Thrown at inspector.go:213

		res = append(res, &DailyStats{
			Queue:     s.Queue,
			Processed: s.Processed,
			Failed:    s.Failed,
			Date:      s.Time,
		})
	}
	return res, nil
}

var (
	// ErrQueueNotFound indicates that the specified queue does not exist.
	ErrQueueNotFound = errors.New("queue not found")

	// ErrQueueNotEmpty indicates that the specified queue is not empty.
	ErrQueueNotEmpty = errors.New("queue is not empty")

	// ErrTaskNotFound indicates that the specified task cannot be found in the queue.
	ErrTaskNotFound = errors.New("task not found")
)

// DeleteQueue removes the specified queue.
//
// If force is set to true, DeleteQueue will remove the queue regardless of
// the queue size as long as no tasks are active in the queue.
// If force is set to false, DeleteQueue will remove the queue only if
// the queue is empty.
//
// If the specified queue does not exist, DeleteQueue returns ErrQueueNotFound.
// If force is set to false and the specified queue is not empty, DeleteQueue
// returns ErrQueueNotEmpty.
func (i *Inspector) DeleteQueue(queue string, force bool) error {
	err := i.rdb.RemoveQueue(queue, force)
	if errors.IsQueueNotFound(err) {
		return fmt.Errorf("%w: queue=%q", ErrQueueNotFound, queue)
	}
	if errors.IsQueueNotEmpty(err) {

View on GitHub (pinned to d135f1439b)