ioredis

Common errors

• Error: connect ECONNREFUSED <ip>:<port>

  cause The Redis server is not running, is configured to listen on a different address/port, or is not accessible from the application's host.
  fix Verify that the Redis server is running and listening on the specified host and port (e.g., `localhost:6379`). Check firewall rules or network configuration.

• ERR unknown command '<command>'

  cause The invoked command is not supported by the connected Redis server version or is misspelled.
  fix Check the Redis documentation for command availability and spelling. Ensure your Redis server version supports the command you are trying to use.

• ERR Wrong number of arguments for '<command>' command

  cause The Redis command was called with an incorrect number of arguments.
  fix Refer to the Redis documentation for the specific command to determine the correct syntax and required number of arguments.

• Error: All masters are down: <ip>:<port> <ip>:<port>...

  cause When connecting to a Redis Cluster, the client cannot reach any of the master nodes, indicating a cluster health issue or misconfiguration.
  fix Verify the health and reachability of all master nodes in your Redis Cluster. Ensure the `startupNodes` configuration is correct.

• TypeError: Cannot read properties of undefined (reading 'set')

  cause This usually indicates that the `Redis` client object was not properly initialized or an asynchronous connection was not `await`ed before attempting to use it.
  fix Ensure the `new Redis()` constructor is correctly called and that any asynchronous setup (like connection events or `await`ing operations) is handled before calling Redis commands.

Warnings

• gotcha For new projects, the `node-redis` library is the recommended JavaScript client, as `ioredis` is currently in a maintenance phase.
  Fix: Consider `node-redis` for new development to benefit from active maintenance and support for newer Redis features.
• breaking Upgrading from v4 to v5 introduced breaking changes. Refer to the official migration guide for details.
  Fix: Consult the "Upgrading from v4 to v5" wiki page at `https://github.com/redis/ioredis/wiki/Upgrading-from-v4-to-v5` before migrating.
• gotcha Client-side blocking timeouts (e.g., for `BLPOP`) became opt-in in v5.9.1, changing default behavior.
  Fix: If your application relies on client-side blocking timeouts, ensure they are explicitly configured after upgrading to v5.9.1 or later.
• gotcha Default IP family selection changed to 0 (IPv4/IPv6 dual-stack preferred) in v5.8.2, which might affect connection behavior in specific network environments.
  Fix: Explicitly set the `family` option in the Redis client configuration (e.g., `family: 4` or `family: 6`) if a specific IP family is required.
• gotcha When using sharded Pub/Sub (`SSUBSCRIBE`), re-subscription after disconnection now happens individually per channel as of v5.8.1.
  Fix: Ensure your application logic correctly handles individual sharded Pub/Sub re-subscriptions and message delivery, as the behavior has changed from bulk re-subscription.

Install

• npm install ioredis npm
• yarn add ioredis yarn
• pnpm add ioredis pnpm

Imports

• Redis
  wrong:

  const Redis = require('ioredis');

  correct:

  import { Redis } from 'ioredis';

Quickstart

Connects to a Redis instance, sets a key-value pair, and retrieves it, demonstrating basic client usage.

import { Redis } from 'ioredis';

async function run() {
  const redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');

  try {
    await redis.set('mykey', 'Hello ioredis!');
    const value = await redis.get('mykey');
    console.log(`Retrieved value: ${value}`);
  } catch (error) {
    console.error('Redis operation failed:', error);
  } finally {
    redis.disconnect();
  }
}

run();