{ "schema_version": 2, "id": "develop/clients/go/error-handling", "title": "Error handling", "url": "https://redis.io/docs/latest/develop/clients/go/error-handling/", "summary": "Learn how to handle errors when using go-redis", "tags": [], "last_updated": "2026-09-09T09:42:14+01:00", "page_type": "content", "content_hash": "574d5878c8a77ca670bf42d2c07a3fe334ad17079bcd319f9b622d9add5c877c", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "go-redis uses **explicit error returns** following Go's idiomatic error handling pattern. Code examples in the documentation often omit error handling for brevity,\nbut it is essential in production code.\nThis page explains how go-redis's error handling works and how to apply\nsome common error handling patterns. For an overview of error types and handling\nstrategies, see [Error handling](https://redis.io/docs/latest/develop/clients/error-handling).\nSee also [Production usage](https://redis.io/docs/latest/develop/clients/go/produsage)\nfor more information on connection management, timeouts, and other aspects of\napp reliability." }, { "id": "error-handling-in-go", "title": "Error handling in Go", "role": "errors", "text": "In Go, functions return errors as a second return value. You can check for errors explicitly with code like the following:\n\n[code example]\n\nCommon error types from go-redis include:\n\n| Error | When it occurs | Recoverable | Recommended action |\n|---|---|---|---|\n| `redis.Nil` | Key does not exist | ✅ | Return default value or fetch from source |\n| `context.DeadlineExceeded` | Operation timeout | ✅ | Retry with backoff |\n| `net.OpError` | Network error | ✅ | Retry with backoff or fall back to alternative |\n| `redis.ResponseError` | Redis error response | ❌ | Fix the command or arguments |\n\nSee [Categories of errors](https://redis.io/docs/latest/develop/clients/error-handling#categories-of-errors)\nfor a more detailed discussion of these errors and their causes." }, { "id": "applying-error-handling-patterns", "title": "Applying error handling patterns", "role": "content", "text": "The [Error handling](https://redis.io/docs/latest/develop/clients/error-handling) overview\ndescribes four main patterns. The sections below show how to implement them in\ngo-redis:" }, { "id": "pattern-1-fail-fast", "title": "Pattern 1: Fail fast", "role": "content", "text": "Return the error immediately if it represents an unrecoverable situation (see\n[Pattern 1: Fail fast](https://redis.io/docs/latest/develop/clients/error-handling#pattern-1-fail-fast)\nfor a full description):\n\n[code example]" }, { "id": "pattern-2-graceful-degradation", "title": "Pattern 2: Graceful degradation", "role": "content", "text": "Check for specific errors and fall back to an alternative (see\n[Pattern 2: Graceful degradation](https://redis.io/docs/latest/develop/clients/error-handling#pattern-2-graceful-degradation)\nfor a full description):\n\n[code example]" }, { "id": "pattern-3-retry-with-backoff", "title": "Pattern 3: Retry with backoff", "role": "content", "text": "Retry on temporary errors such as timeouts (see\n[Pattern 3: Retry with backoff](https://redis.io/docs/latest/develop/clients/error-handling#pattern-3-retry-with-backoff)\nfor a full description). go-redis has built-in retry logic with\nconfigurable timing and backoffs. See [Retries](https://redis.io/docs/latest/develop/clients/go/produsage#retries) for more information. Note also that\nyou can configure timeouts (which are one of the most common causes of\ntemporary errors) for connections and commands. See [Timeouts](https://redis.io/docs/latest/develop/clients/go/produsage#timeouts) for more information." }, { "id": "pattern-4-log-and-continue", "title": "Pattern 4: Log and continue", "role": "content", "text": "Log non-critical errors and continue (see\n[Pattern 4: Log and continue](https://redis.io/docs/latest/develop/clients/error-handling#pattern-4-log-and-continue)\nfor a full description):\n\n[code example]\n\nNote that go-redis also supports [OpenTelemetry](https://opentelemetry.io/)\ninstrumentation to monitor performance and trace the execution of Redis commands. See [Observability](https://redis.io/docs/latest/develop/clients/go#observability) for more information." }, { "id": "see-also", "title": "See also", "role": "related", "text": "- [Error handling](https://redis.io/docs/latest/develop/clients/error-handling)\n- [Production usage](https://redis.io/docs/latest/develop/clients/go/produsage)\n- [Observability](https://redis.io/docs/latest/develop/clients/go#observability)" } ], "examples": [ { "id": "error-handling-in-go-ex0", "language": "go", "code": "result, err := rdb.Get(ctx, key).Result()\nif err != nil {\n // Handle the error\n}", "section_id": "error-handling-in-go" }, { "id": "pattern-1-fail-fast-ex0", "language": "go", "code": "result, err := rdb.Get(ctx, key).Result()\nif err != nil {\n // This indicates a problem that should be fixed\n return err\n}", "section_id": "pattern-1-fail-fast" }, { "id": "pattern-2-graceful-degradation-ex0", "language": "go", "code": "result, err := rdb.Get(ctx, key).Result()\nif err != nil {\n if err == redis.Nil {\n // Key doesn't exist, try database\n return database.Get(ctx, key)\n }\n if _, ok := err.(net.Error); ok {\n // Network error, use fallback\n logger.Warn(\"Cache unavailable, using database\")\n return database.Get(ctx, key)\n }\n return err\n}\nreturn result, nil", "section_id": "pattern-2-graceful-degradation" }, { "id": "pattern-4-log-and-continue-ex0", "language": "go", "code": "err := rdb.SetEx(ctx, key, value, 3600*time.Second).Err()\nif err != nil {\n if _, ok := err.(net.Error); ok {\n logger.Warnf(\"Failed to cache %s, continuing without cache\", key)\n // Application continues normally\n } else {\n return err\n }\n}", "section_id": "pattern-4-log-and-continue" } ] }