{ "schema_version": 2, "id": "develop/clients/nodejs/error-handling", "title": "Error handling", "url": "https://redis.io/docs/latest/develop/clients/nodejs/error-handling/", "summary": "Learn how to handle errors when using node-redis.", "tags": [], "last_updated": "2026-09-08T15:03:39+01:00", "page_type": "content", "content_hash": "82b433ca55198a284acb6a3bc4621d9a5311b0ad6befa5410bb36a973072810e", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "node-redis uses\n[**promises**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)\nfor error handling. Most Redis JavaScript examples\nthroughout the documentation mainly show the \"happy path\" and omit error\nhandling for brevity. This page shows how to apply error handling\ntechniques in node-redis for real world code.\nFor an overview of some common general error types and strategies for\nhandling them, see\n[Error handling](https://redis.io/docs/latest/develop/clients/error-handling).\nSee also [Production usage](https://redis.io/docs/latest/develop/clients/nodejs/produsage)\nfor more information on connection management, timeouts, and other aspects of\napp reliability." }, { "id": "common-error-types", "title": "Common error types", "role": "content", "text": "node-redis throws errors as rejected promises. Common error types include:\n\n| Error | When it occurs | Recoverable | Recommended action |\n|---|---|---|---|\n| `ECONNREFUSED` | Connection refused | ✅ | Retry with backoff or fall back |\n| `ETIMEDOUT` | Command timeout | ✅ | Retry with backoff |\n| `ECONNRESET` | Connection reset by peer | ✅ | Retry with backoff |\n| `EAI_AGAIN` | DNS resolution failure | ✅ | Retry with backoff |\n| `ReplyError` (`WRONGTYPE`) | Type mismatch | ❌ | Fix schema or code |\n| `ReplyError` (`BUSY`, `TRYAGAIN`, `LOADING`) | Redis busy/loading | ⚠️ | Retry with backoff (bounded) |\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": "asyncawait-in-examples", "title": "Async/await in examples", "role": "content", "text": "The examples on this page and throughout the node-redis docs use `async/await`\nstyle for clarity.\n\n[code example]\n\nAlternatively, you can use promise chains with `.then()` and `.catch()`:\n\n[code example]" }, { "id": "error-events", "title": "Error events", "role": "errors", "text": "Node-Redis provides [multiple events to handle various scenarios](https://github.com/redis/node-redis?tab=readme-ov-file#events), among which the most critical is the `error` event.\n\nThis event is triggered whenever an error occurs within the client.\n\nIt is crucial to listen for error events.\n\nIf a client does not register at least one error listener and an error occurs, the system will throw that error, potentially causing the Node.js process to exit unexpectedly.\nSee [the EventEmitter docs](https://nodejs.org/api/events.html#events_error_events) for more details.\n\n[code example]" }, { "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)\noverview describes four common error handling patterns. The sections\nbelow show how to implement these patterns in node-redis:" }, { "id": "pattern-1-fail-fast", "title": "Pattern 1: Fail fast", "role": "content", "text": "Catch specific errors 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 connection 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 like 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\nNote that you can also configure node-redis to reconnect to the\nserver automatically when the connection is lost. See\n[Reconnect after disconnection](https://redis.io/docs/latest/develop/clients/nodejs/connect#reconnect-after-disconnection)\nfor 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]" }, { "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/nodejs/produsage)" } ], "examples": [ { "id": "asyncawait-in-examples-ex0", "language": "javascript", "code": "// Using async/await (shown in examples below)\ntry {\n const result = await client.get(key);\n // Handle success\n} catch (error) {\n // Handle error\n}", "section_id": "asyncawait-in-examples" }, { "id": "asyncawait-in-examples-ex1", "language": "javascript", "code": "// Using promise chains (equivalent approach)\nclient.get(key)\n .then(result => {\n // Handle success\n })\n .catch(error => {\n // Handle error\n });", "section_id": "asyncawait-in-examples" }, { "id": "error-events-ex0", "language": "typescript", "code": "const client = createClient({\n // ... client options\n});\n// Always ensure there's a listener for errors in the client to prevent process crashes due to unhandled errors\nclient.on('error', error => {\n console.error(`Redis client error:`, error);\n});", "section_id": "error-events" }, { "id": "pattern-1-fail-fast-ex0", "language": "javascript", "code": "try {\n await client.get(key);\n} catch (err) {\n if (err.name === 'ReplyError' && /WRONGTYPE|ERR /.test(err.message)) {\n throw err; // Fix code or data type\n }\n throw err;\n}", "section_id": "pattern-1-fail-fast" }, { "id": "pattern-2-graceful-degradation-ex0", "language": "javascript", "code": "try {\n const val = await client.get(key);\n if (val != null) return val;\n} catch (err) {\n if (['ECONNREFUSED','ECONNRESET','ETIMEDOUT','EAI_AGAIN'].includes(err.code)) {\n logger.warn('Cache unavailable; falling back to DB');\n return database.get(key);\n }\n throw err;\n}\nreturn database.get(key);", "section_id": "pattern-2-graceful-degradation" }, { "id": "pattern-3-retry-with-backoff-ex0", "language": "javascript", "code": "async function getWithRetry(key, { attempts = 3, baseDelayMs = 100 } = {}) {\n let delay = baseDelayMs;\n for (let i = 0; i < attempts; i++) {\n try {\n return await client.get(key);\n } catch (err) {\n if (\n i < attempts - 1 &&\n (['ETIMEDOUT','ECONNRESET','EAI_AGAIN'].includes(err.code) ||\n (err.name === 'ReplyError' && /(BUSY|TRYAGAIN|LOADING)/.test(err.message)))\n ) {\n await new Promise(r => setTimeout(r, delay));\n delay *= 2;\n continue;\n }\n throw err;\n }\n }\n}", "section_id": "pattern-3-retry-with-backoff" }, { "id": "pattern-4-log-and-continue-ex0", "language": "javascript", "code": "try {\n await client.setEx(key, 3600, value);\n} catch (err) {\n if (['ECONNREFUSED','ECONNRESET','ETIMEDOUT','EAI_AGAIN'].includes(err.code)) {\n logger.warn(`Failed to cache ${key}, continuing without cache`);\n } else {\n throw err;\n }\n}", "section_id": "pattern-4-log-and-continue" } ] }