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), the task will moved to the archive for debugging and inspection purposes and won't be automatically retried (You can still manually run task using CLI or WebUI).

Customize Task Max Retry

You can specify the maximum number of 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 the maximum retry count for some task type, you can set it as a default option for the task type.

// By default, all "feed:import" tasks will have max-retry set to 5.
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 archived 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)
}