ioredis

library5.10.1jsnpmunverified

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.

database

npm install ioredis

github ↗package ↗

INSTALL

IMPORT

SIG · IOREDIS

ioredis

databasejavascriptv5.10.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Redis

✓ import { Redis } from 'ioredis';

✗ import Redis from 'ioredis'; // Deprecated in next major version const Redis = require('ioredis'); // CommonJS

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.

Cluster

✓ import { Cluster } from 'ioredis';

✗ const Cluster = require('ioredis').Cluster; // CommonJS

For Redis Cluster, import the `Cluster` class. Direct import from `ioredis` works for both ESM and CommonJS via named exports.

RedisOptions

✓ import { RedisOptions, ClusterOptions } from 'ioredis';

✗ import { Options } from 'ioredis';

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.

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.

import { Redis, Cluster } from 'ioredis'; // Connect to a single Redis instance async function connectToSingleRedis() { const redis = new Redis({ port: 6379, host: process.env.REDIS_HOST || '127.0.0.1', password: process.env.REDIS_PASSWORD || undefined, db: 0, }); redis.on('error', (err) => { console.error('Redis Client Error:', err); }); redis.on('connect', () => { console.log('Connected to single Redis instance.'); }); try { await redis.set('mykey', 'Hello ioredis!'); const value = await redis.get('mykey'); console.log(`Value for mykey: ${value}`); } catch (error) { console.error('Operation failed:', error); } finally { await redis.quit(); console.log('Disconnected from single Redis instance.'); } } // Connect to a Redis Cluster async function connectToRedisCluster() { const cluster = new Cluster([ { host: process.env.REDIS_CLUSTER_HOST_1 || '127.0.0.1', port: 6379 }, { host: process.env.REDIS_CLUSTER_HOST_2 || '127.0.0.1', port: 6380 }, ], { slotsRefreshInterval: 5000, // Explicitly enable for proactive refreshes redisOptions: { password: process.env.REDIS_CLUSTER_PASSWORD || undefined }, }); cluster.on('error', (err) => { console.error('Redis Cluster Error:', err); }); cluster.on('connect', () => { console.log('Connected to Redis Cluster.'); }); try { await cluster.set('clusterkey', 'Hello Cluster!'); const value = await cluster.get('clusterkey'); console.log(`Value for clusterkey: ${value}`); } catch (error) { console.error('Cluster operation failed:', error); } finally { await cluster.quit(); console.log('Disconnected from Redis Cluster.'); } } connectToSingleRedis(); // connectToRedisCluster(); // Uncomment to test cluster connection

Debug

Known issues

deprecatedioredis 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.

fix

For new applications, consider `node-redis`. For existing ioredis projects, ensure robust error handling and keep up-to-date with patch releases.

affects: >=5.0.0

breakingUpgrading to v5 requires Node.js version 12 or newer. Previous versions (v4) supported Node.js 8+.

fix

Ensure your Node.js runtime environment is version 12.x or higher before upgrading ioredis to v5.x.x.

affects: >=5.0.0

breakingIn v5, ioredis exclusively uses native Promises, dropping support for third-party Promise implementations like Bluebird. Setting `Redis.Promise = require('bluebird')` becomes a no-op.

fix

Remove any custom Promise implementations, as ioredis v5 will use native Promises.

affects: >=5.0.0

breakingVersion 5 ships with official TypeScript declarations. If you previously used `@types/ioredis`, you should uninstall it to avoid type conflicts.

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'`).

affects: >=5.0.0

breakingThe `allowUsernameInURI` option has been removed in v5. The username part in Redis URIs will now always be used, rather than being ignored by default.

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`).

affects: >=5.0.0

breakingFor 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.

fix

If you rely on proactive cluster slot refreshing, explicitly set `slotsRefreshInterval` in your `Cluster` options, e.g., `new Cluster(nodes, { slotsRefreshInterval: 5000 })`.

affects: >=5.0.0-beta.1

breakingClient-side blocking commands (e.g., `BLPOP`) with timeouts became opt-in in v5.9.1. This change affects how ioredis handles certain blocking commands.

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.

affects: >=5.9.1

breakingThe `Cluster#masterNodes` and `Cluster#nodes` properties were removed in v5. They are replaced by `Cluster#nodes('masters')` and `Cluster#nodes('all')` respectively.

fix

Update calls to these properties using the new method syntax, e.g., `cluster.nodes('masters')` or `cluster.nodes('all')`.

affects: >=5.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED <address>:<port>

The ioredis client failed to establish a connection to the Redis server at the specified address and port.

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.

TypeError: Redis is not a constructor

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.

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()`.

ReplyError: MOVED <slot> <address>:<port>

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.

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.

ReplyError: WRONGPASS Invalid username-password pair or user is disabled

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.

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.

Upgrade

Version history

5.10.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/luin/ioredis ↗

packagehttps://www.npmjs.com/package/ioredis ↗