Task Retry

This page explains how to configure task retries.

Default behavior

By default, asynq will retry a task up to 25 times. Every time a task is retried it uses an exponential backoff strategy to calculate the retry delay. If a task exhausts all of its retry count (default: 25), then the task will moved to the archive for debugging and inspection purposes and won't be retried.

Customize Task Retry

You can specify how many times a task can be retried using asynq.MaxRetry option when enqueueing a task.

Example:

client.Enqueue(task, asynq.MaxRetry(5))

This specifies that the task should be retired up to five times.

Alternatively, if you want to specify maximum retry count for some task type, you can set it as a default option.

client.SetDefaultOptions("feed:import", asynq.MaxRetry(5))

task := asynq.NewTask("feed:import, nil)
client.Enqueue(task) // MaxRetry is set to 5

Customize Retry Delay

You can specify how to calculate retry delay using RetryDelayFunc option in Config.

Signature of RetryDelayFunc:

// n is the number of times the task has been retried
// e is the error returned by the task handler
// t is the task in question
RetryDelayFunc func(n int, e error, t *asynq.Task) time.Duration

Example:

srv := asynq.NewServer(redis, asynq.Config{
    Concurrency: 20,
    RetryDelayFunc: func(n int, e error, t *asynq.Task) time.Duration {
        return 2 * time.Second
    },
})

This specifies that all failed task will wait two seconds before being processed again.

Skip Retry

If Handler.ProcessTask returns a SkipRetry error, the task will be moved to archive regardless of the number of remaining retry count. The returned error can be SkipRetry or an error which wraps the SkipRetry error.

func ExampleHandler(ctx context.Context, task *asynq.Task) error {
    // Task handling logic here...
    // If the handler knows that the task does not need a retry, then return SkipRetry
    return fmt.Errorf("reason for skipping retry: %w", asynq.SkipRetry)
}