{"id":10398,"library":"ioredis","title":"ioredis Redis Client","description":"ioredis is a robust, performance-focused, and full-featured Redis client for Node.js, currently at version 5.10.1. It provides comprehensive support for various Redis topologies including Cluster, Sentinel, and offers advanced features like Pipelining, Streams, Pub/Sub (with binary messages), and Lua scripting. While ioredis is a stable and widely used project, its maintenance is now on a best-effort basis for relevant issues. For new projects, the official `node-redis` client is explicitly recommended by the maintainers, as it is actively maintained and supports newer Redis commands and capabilities from Redis Stack and Redis 8. ioredis is written entirely in TypeScript, providing official type declarations, and is compatible with Node.js versions 12 and above, and Redis versions 2.6.12 through 7.x. Its differentiators include high performance, a Promise-based API (also supporting callbacks), sophisticated error handling, transparent key prefixing, and autopipelining. Releases are frequent for bug fixes and minor features.","status":"maintenance","version":"5.10.1","language":"javascript","source_language":"en","source_url":"git://github.com/luin/ioredis","tags":["javascript","redis","cluster","sentinel","pipelining","typescript"],"install":[{"cmd":"npm install ioredis","lang":"bash","label":"npm"},{"cmd":"yarn add ioredis","lang":"bash","label":"yarn"},{"cmd":"pnpm add ioredis","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v5.2.5, named export `Redis` is recommended for ESM to ensure proper TypeScript constructor typing. The default export `import Redis from 'ioredis'` is still supported but will be deprecated in the next major version. CommonJS `require` remains valid.","wrong":"import Redis from 'ioredis'; // Deprecated in next major version\nconst Redis = require('ioredis'); // CommonJS","symbol":"Redis","correct":"import { Redis } from 'ioredis';"},{"note":"For Redis Cluster, import the `Cluster` class. Direct import from `ioredis` works for both ESM and CommonJS via named exports.","wrong":"const Cluster = require('ioredis').Cluster; // CommonJS","symbol":"Cluster","correct":"import { Cluster } from 'ioredis';"},{"note":"TypeScript types for client configuration are `RedisOptions` for a single client and `ClusterOptions` for a cluster client. It's crucial for type-checking when configuring clients.","wrong":"import { Options } from 'ioredis';","symbol":"RedisOptions","correct":"import { RedisOptions, ClusterOptions } from 'ioredis';"}],"quickstart":{"code":"import { Redis, Cluster } from 'ioredis';\n\n// Connect to a single Redis instance\nasync function connectToSingleRedis() {\n  const redis = new Redis({\n    port: 6379,\n    host: process.env.REDIS_HOST || '127.0.0.1',\n    password: process.env.REDIS_PASSWORD || undefined,\n    db: 0,\n  });\n\n  redis.on('error', (err) => {\n    console.error('Redis Client Error:', err);\n  });\n\n  redis.on('connect', () => {\n    console.log('Connected to single Redis instance.');\n  });\n\n  try {\n    await redis.set('mykey', 'Hello ioredis!');\n    const value = await redis.get('mykey');\n    console.log(`Value for mykey: ${value}`);\n  } catch (error) {\n    console.error('Operation failed:', error);\n  } finally {\n    await redis.quit();\n    console.log('Disconnected from single Redis instance.');\n  }\n}\n\n// Connect to a Redis Cluster\nasync function connectToRedisCluster() {\n  const cluster = new Cluster([\n    { host: process.env.REDIS_CLUSTER_HOST_1 || '127.0.0.1', port: 6379 },\n    { host: process.env.REDIS_CLUSTER_HOST_2 || '127.0.0.1', port: 6380 },\n  ], {\n    slotsRefreshInterval: 5000, // Explicitly enable for proactive refreshes\n    redisOptions: { password: process.env.REDIS_CLUSTER_PASSWORD || undefined },\n  });\n\n  cluster.on('error', (err) => {\n    console.error('Redis Cluster Error:', err);\n  });\n\n  cluster.on('connect', () => {\n    console.log('Connected to Redis Cluster.');\n  });\n\n  try {\n    await cluster.set('clusterkey', 'Hello Cluster!');\n    const value = await cluster.get('clusterkey');\n    console.log(`Value for clusterkey: ${value}`);\n  } catch (error) {\n    console.error('Cluster operation failed:', error);\n  } finally {\n    await cluster.quit();\n    console.log('Disconnected from Redis Cluster.');\n  }\n}\n\nconnectToSingleRedis();\n// connectToRedisCluster(); // Uncomment to test cluster connection","lang":"typescript","description":"Demonstrates connecting to a single Redis instance and a Redis Cluster, performing basic set/get operations, handling errors, and ensuring proper disconnection. Uses environment variables for sensitive connection details."},"warnings":[{"fix":"For new applications, consider `node-redis`. For existing ioredis projects, ensure robust error handling and keep up-to-date with patch releases.","message":"ioredis is currently in maintenance mode with 'best-effort' support. For new projects, the maintainers explicitly recommend using the `node-redis` client, which is actively developed and supports newer Redis features.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Ensure your Node.js runtime environment is version 12.x or higher before upgrading ioredis to v5.x.x.","message":"Upgrading to v5 requires Node.js version 12 or newer. Previous versions (v4) supported Node.js 8+.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Remove any custom Promise implementations, as ioredis v5 will use native Promises.","message":"In v5, ioredis exclusively uses native Promises, dropping support for third-party Promise implementations like Bluebird. Setting `Redis.Promise = require('bluebird')` becomes a no-op.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Run `npm uninstall @types/ioredis`. Review your TypeScript code for minor type errors, especially for imports (e.g., `import * as Redis from 'ioredis'` is now `import { Redis } from 'ioredis'`).","message":"Version 5 ships with official TypeScript declarations. If you previously used `@types/ioredis`, you should uninstall it to avoid type conflicts.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"If you don't intend to pass a username to Redis, omit the username part from your connection URI (e.g., `redis://:password@host:port`).","message":"The `allowUsernameInURI` option has been removed in v5. The username part in Redis URIs will now always be used, rather than being ignored by default.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"If you rely on proactive cluster slot refreshing, explicitly set `slotsRefreshInterval` in your `Cluster` options, e.g., `new Cluster(nodes, { slotsRefreshInterval: 5000 })`.","message":"For Redis Cluster, the `slotsRefreshInterval` option is now disabled by default. Previously, it defaulted to 5000ms. This means ioredis will not proactively refresh cluster slots without explicit configuration.","severity":"breaking","affected_versions":">=5.0.0-beta.1"},{"fix":"Review usage of blocking commands. If you experience unexpected behavior or timeouts, consult the ioredis documentation for how to explicitly enable client-side blocking timeouts if required.","message":"Client-side blocking commands (e.g., `BLPOP`) with timeouts became opt-in in v5.9.1. This change affects how ioredis handles certain blocking commands.","severity":"breaking","affected_versions":">=5.9.1"},{"fix":"Update calls to these properties using the new method syntax, e.g., `cluster.nodes('masters')` or `cluster.nodes('all')`.","message":"The `Cluster#masterNodes` and `Cluster#nodes` properties were removed in v5. They are replaced by `Cluster#nodes('masters')` and `Cluster#nodes('all')` respectively.","severity":"breaking","affected_versions":">=5.0.0"}],"env_vars":null,"search_vec":"'12':119 '2.6.12':125 '5.10.1':22 '7':127 '8':102 'activ':88 'advanc':36 'also':139 'api':138 'autopipelin':149 'base':137 'basi':66 'best':64 'best-effort':63 'binari':43 'bug':154 'callback':141 'capabl':96 'client':3,16,78 'cluster':32,161 'command':94 'compat':115 'comprehens':25 'current':19 'declar':112 'differenti':130 'effort':65 'entir':106 'error':143 'explicit':80 'featur':14,37,158 'fix':155 'focus':10 'frequent':152 'full':13 'full-featur':12 'handl':144 'high':132 'includ':31,131 'ioredi':1,4,49,103 'issu':69 'javascript':159 'key':146 'like':38 'lua':46 'maintain':84,89 'mainten':58 'messag':44 'minor':157 'new':71 'newer':92 'node':76 'node-redi':75 'node.js':18,117 'offer':35 'offici':74,110 'perform':9,133 'performance-focus':8 'pipelin':39,163 'prefix':147 'project':56,72 'promis':136 'promise-bas':135 'provid':24,109 'pub/sub':41 'recommend':81 'redi':2,15,29,77,93,98,101,123,160 'releas':150 'relev':68 'robust':7 'script':47 'sentinel':33,162 'sophist':142 'stabl':52 'stack':99 'stream':40 'support':26,91,140 'topolog':30 'transpar':145 'type':111 'typescript':108,164 'use':55 'various':28 'version':21,118,124 'wide':54 'written':105 'x':128","created_at":"2026-04-18T08:58:36.072488+00:00","updated_at":"2026-04-19T05:46:53.411984+00:00","problems":[{"fix":"Verify that the Redis server is running and accessible from the application's host. Check firewall rules, network connectivity, and ensure the correct host and port are configured in the ioredis client. If using a cloud provider, check security groups and instance status.","cause":"The ioredis client failed to establish a connection to the Redis server at the specified address and port.","error":"Error: connect ECONNREFUSED <address>:<port>"},{"fix":"For ESM with TypeScript, use `import { Redis } from 'ioredis';`. For CommonJS, use `const Redis = require('ioredis').default || require('ioredis');` and always instantiate with `new Redis()`.","cause":"This typically occurs in ESM projects when `import Redis from 'ioredis'` is used with TypeScript, or when `new` keyword is missing, or incorrect CommonJS `require` usage in an ESM context.","error":"TypeError: Redis is not a constructor"},{"fix":"Ensure you are using `new Cluster(...)` for Redis Cluster connections. The `ioredis` Cluster client should handle `MOVED` redirections automatically. If this persists, increase `slotsRefreshTimeout` or `retryDelayOnMoved` options in the Cluster configuration. It can also occur during failovers or resharding.","cause":"This error occurs in a Redis Cluster when a client attempts to access a key on a node that does not own the corresponding hash slot. It means the client's slot-to-node mapping is outdated or it's connecting to a single node instead of the cluster.","error":"ReplyError: MOVED <slot> <address>:<port>"},{"fix":"Verify the Redis password and username (if ACLs are enabled) in your client configuration matches the Redis server's configuration. For managed services, check token validity or credential rotation policies.","cause":"The Redis server rejected the provided authentication credentials (username and/or password). This could be due to incorrect credentials, expired tokens, or the user being disabled.","error":"ReplyError: WRONGPASS Invalid username-password pair or user is disabled"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/luin/ioredis","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/ioredis","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}