{
  "schema_version": 2,
  "id": "develop/clients/dotnet/error-handling",
  "title": "Error handling",
  "url": "https://redis.io/docs/latest/develop/clients/dotnet/error-handling/",
  "summary": "Learn how to handle errors when using StackExchange.Redis.",
  "tags": [],
  "last_updated": "2026-09-08T15:21:05+01:00",
  "page_type": "content",
  "content_hash": "5b672d498f9ef6de1e42d8a72b6fdfaf8b808e44267c42ead08ad653c3a06479",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "`StackExchange.Redis` uses **exceptions** to signal errors. Code examples in the\ndocumentation often omit error handling for brevity, but it is essential in production code.\nThis page explains how error handling works in `StackExchange.Redis` and how to apply common\nerror handling patterns.\n\nFor an overview of error types and handling strategies, see [Error handling](https://redis.io/docs/latest/develop/clients/error-handling).\nSee also [Production usage](https://redis.io/docs/latest/develop/clients/dotnet/produsage)\nfor more information on connection management, timeouts, and other aspects of\napp reliability."
    },
    {
      "id": "exception-types",
      "title": "Exception types",
      "role": "errors",
      "text": "`StackExchange.Redis` throws exceptions to signal errors. Common exception types include:\n\n| Exception | When it occurs | Recoverable | Recommended action |\n|---|---|---|---|\n| `RedisConnectionException` | Connection refused or lost | ✅ | Retry with backoff or fall back |\n| `RedisTimeoutException` | Operation exceeded timeout | ✅ | Retry with backoff |\n| `RedisCommandException` | Invalid command or arguments | ❌ | Fix the command or arguments |\n| `RedisServerException` | Invalid operation on server | ❌ | Fix the operation or data |\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\n`StackExchange.Redis`:"
    },
    {
      "id": "pattern-1-fail-fast",
      "title": "Pattern 1: Fail fast",
      "role": "content",
      "text": "Catch specific exceptions that represent unrecoverable errors and re-throw them (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": "Catch specific errors and fall back to an alternative, where possible (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):\n\n[code example]\n\nSee also [Timeouts](https://redis.io/docs/latest/develop/clients/dotnet/produsage#timeouts)\nfor more information on configuring timeouts in `StackExchange.Redis`."
    },
    {
      "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]"
    },
    {
      "id": "async-error-handling",
      "title": "Async error handling",
      "role": "content",
      "text": "Error handling works the usual way with `async`/`await`, as shown in the\nexample below:\n\n[code example]"
    },
    {
      "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/dotnet/produsage)"
    }
  ],
  "examples": [
    {
      "id": "pattern-1-fail-fast-ex0",
      "language": "csharp",
      "code": "using StackExchange.Redis;\n\nvar muxer = ConnectionMultiplexer.Connect(\"localhost:6379\");\nvar db = muxer.GetDatabase();\n\ntry {\n    var result = db.StringGet(\"key\");\n} catch (RedisCommandException) {\n    // This indicates a bug in the code, such as using\n    // StringGet on a list key.\n    throw;\n}",
      "section_id": "pattern-1-fail-fast"
    },
    {
      "id": "pattern-2-graceful-degradation-ex0",
      "language": "csharp",
      "code": "try {\n    var cachedValue = db.StringGet(key);\n    return cachedValue.ToString();\n} catch (RedisConnectionException) {\n    logger.LogWarning(\"Cache unavailable, using database\");\n\n    // Fallback to database\n    return database.Get(key);\n}",
      "section_id": "pattern-2-graceful-degradation"
    },
    {
      "id": "pattern-3-retry-with-backoff-ex0",
      "language": "csharp",
      "code": "const int maxRetries = 3;\nint retryDelay = 100;\n\nfor (int attempt = 0; attempt < maxRetries; attempt++) {\n    try {\n        return db.StringGet(key).ToString();\n    } catch (RedisTimeoutException) {\n        if (attempt < maxRetries - 1) {\n            Thread.Sleep(retryDelay);\n            retryDelay *= 2;  // Exponential backoff\n        } else {\n            throw;\n        }\n    }\n}",
      "section_id": "pattern-3-retry-with-backoff"
    },
    {
      "id": "pattern-4-log-and-continue-ex0",
      "language": "csharp",
      "code": "try {\n    db.StringSet(key, value, TimeSpan.FromSeconds(3600));\n} catch (RedisConnectionException) {\n    logger.LogWarning($\"Failed to cache {key}, continuing without cache\");\n    // Application continues normally\n}",
      "section_id": "pattern-4-log-and-continue"
    },
    {
      "id": "async-error-handling-ex0",
      "language": "csharp",
      "code": "using StackExchange.Redis;\n\nvar muxer = ConnectionMultiplexer.Connect(\"localhost:6379\");\nvar db = muxer.GetDatabase();\n\nasync Task<string> GetWithFallbackAsync(string key) {\n    try {\n        var result = await db.StringGetAsync(key);\n        if (result.HasValue) {\n            return result.ToString();\n        }\n    } catch (RedisConnectionException) {\n        logger.LogWarning(\"Cache unavailable\");\n        return await database.GetAsync(key);\n    }\n    \n    return await database.GetAsync(key);\n}",
      "section_id": "async-error-handling"
    }
  ]
}