Need help with go-retry?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

253 Stars 14 Forks Apache License 2.0 8 Commits 0 Opened issues


Go library for retrying with configurable backoffs

Services available


Need anything else?

Contributors list

# 4,158
6 commits
# 250,256
1 commit


GoDoc GitHub Actions

Retry is a Go library for facilitating retry logic and backoff. It's highly extensible with full control over how and when retries occur. You can also write your own custom backoff functions by implementing the Backoff interface.


  • Extensible - Inspired by Go's built-in HTTP package, this Go backoff and retry library is extensible via middleware. You can write custom backoff functions or use a provided filter.

  • Independent - No external dependencies besides the Go standard library, meaning it won't bloat your project.

  • Concurrent - Unless otherwise specified, everything is safe for concurrent use.

  • Context-aware - Use native Go contexts to control cancellation.


Here is an example use for connecting to a database using Go's

package main

import ( "context" "database/sql" "log" "time"

"" )

func main() { db, err := sql.Open("mysql", "...") if err != nil { log.Fatal(err) }

ctx := context.Background() err := retry.Fibonacci(ctx, 1*time.Second, func(ctx context.Context) error { if err := db.PingContext(ctx); err != nil { // This marks the error as retryable return retry.RetryableError(err) } return nil }) if err != nil { log.Fatal(err) } }


In addition to your own custom algorithms, there are built-in algorithms for backoff in the library.


A very rudimentary backoff, just returns a constant value. Here is an example:

1s -> 1s -> 1s -> 1s -> 1s -> 1s


NewConstant(1 * time.Second)


Arguably the most common backoff, the next value is double the previous value. Here is an example:

1s -> 2s -> 4s -> 8s -> 16s -> 32s -> 64s


NewExponential(1 * time.Second)


The Fibonacci backoff uses the Fibonacci sequence to calculate the backoff. The next value is the sum of the current value and the previous value. This means retires happen quickly at first, but then gradually take slower, ideal for network-type issues. Here is an example:

1s -> 1s -> 2s -> 3s -> 5s -> 8s -> 13s


NewFibonacci(1 * time.Second)

Modifiers (Middleware)

The built-in backoff algorithms never terminate and have no caps or limits - you control their behavior with middleware. There's built-in middleware, but you can also write custom middleware.


To reduce the changes of a thundering herd, add random jitter to the returned value.

b, err := NewFibonacci(1 * time.Second)
if err != nil {
  // handle err

// Return the next value, +/- 500ms b = WithJitter(500*time.Millisecond, b)

// Return the next value, +/- 5% of the result b = WithJitterPercent(5, b)


To terminate a retry, specify the maximum number of retry attempts. Note this is retries, not attempts. Attempts is retries - 1.

b, err := NewFibonacci(1 * time.Second)
if err != nil {
  // handle err

// Stop when the 5th retry has failed. In this example, the worst case elapsed // time would be 1s + 1s + 2s + 3s = 7s. b = WithMaxRetries(4, b)


To ensure an individual calculated duration never exceeds a value, use a cap:

b, err := NewFibonacci(1 * time.Second)
if err != nil {
  // handle err

// Ensure the maximum value is 2s. In this example, the sleep values would be // 1s, 1s, 2s, 2s, 2s, 2s... b = WithCappedDuration(2 * time.Second, b)


For a best-effort limit on the total execution time, specify a max duration:

b, err := NewFibonacci(1 * time.Second)
if err != nil {
  // handle err

// Ensure the maximum total retry time is 5s. b = WithMaxDuration(5 * time.Second, b)


Here are benchmarks against some other popular Go backoff and retry libraries. You can run these benchmarks yourself via the

folder. Commas and spacing fixed for clarity.
Benchmark/cenkalti-7      13,052,668     87.3 ns/op
Benchmark/lestrrat-7         902,044    1,355 ns/op
Benchmark/sethvargo-7    203,914,245     5.73 ns/op

Notes and Caveats

  • Randomization uses
    seeded with the Unix timestamp instead of
  • Ordering of addition of multiple modifiers will make a difference. For example; ensure you add
    , otherwise it may early out too early. Another example is you could add
    before or after capping depending on your desired outcome.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.