redis/node-redis · error · Error

no replicas available for read

Error message

no replicas available for read

What it means

Thrown by #getClient() on the replica read path when this.#replicaClients.length === 0 (sentinel/index.ts:1121). It fires for read commands routed to replicas (no clientInfo) after the replica client array was found empty — meaning replicaPoolSize was configured > 0 (useReplicas true) but no replica connection is currently established, e.g. all replicas down, none enumerated by sentinel, or a reconfigure in progress.

Source

Thrown at packages/client/lib/sentinel/index.ts:1122

  }

  #handlePubSubControlChannel(channel: Buffer, _message: Buffer) {
    this.#trace("pubsub control channel message on " + channel);
    this.#resetInBackground();
  }

  // if clientInfo is defined, it corresponds to a master client in the #masterClients array, otherwise loop around replicaClients
  #getClient(clientInfo?: ClientInfo): RedisClientType<RedisModules, RedisFunctions, RedisScripts, RespVersions, TypeMapping> {
    if (clientInfo !== undefined) {
      return this.#masterClients[clientInfo.id];
    }

    if (this.#replicaClientsIdx >= this.#replicaClients.length) {
      this.#replicaClientsIdx = 0;
    }

    if (this.#replicaClients.length == 0) {
      throw new Error("no replicas available for read");
    }

    return this.#replicaClients[this.#replicaClientsIdx++];
  }

  async #reset() {
    /* closing / don't reset */
    if (this.#isReady == false || this.#destroy == true) {
      return;
    }

    // already in #connect()
    if (this.#connectPromise !== undefined) {
      this.#anotherReset = true;
      return await this.#connectPromise;
    }

    try {

View on GitHub (pinned to bb5beb5657)

Solutions

  1. If you do not actually need replica reads, set replicaPoolSize to 0 (default) so reads route to the master.
  2. Ensure at least one healthy replica exists and is reachable from the client before issuing reads.
  3. Retry the read after a short backoff to ride out a reconfigure/failover window.
  4. Verify sentinelReplicas(name) returns nodes and that nodeClientOptions let the client dial them (host/port mapping, TLS, nodeAddressMap).

Example fix

// before
const opts = { name, sentinelRootNodes, replicaPoolSize: 2 };
// reads fail immediately if replicas lag behind connect
// after — fall back to master when no replicas are needed
const opts = { name, sentinelRootNodes, replicaPoolSize: 0 };
Defensive patterns

Strategy: retry

Validate before calling

// Before issuing a replica read, confirm the sentinel client actually has replicas.
// (useReplicas is true when replicaPoolSize > 0; if 0, reads go to master and this error cannot fire.)
function wantsReplicaReads(opts) {
  return (opts.replicaPoolSize ?? 0) > 0;
}
// If unsure replicas are up, prefer replicaPoolSize: 0 for correctness over read scaling.

Try / catch

async function readWithReplicaFallback(sentinel, fn) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await sentinel.execute(fn); // replica read path
    } catch (e) {
      if (e instanceof Error && /no replicas available for read/.test(e.message)) {
        await new Promise(r => setTimeout(r, 200 * (attempt + 1)));
        continue;
      }
      throw e;
    }
  }
  // last resort: route to master by using a master lease
  return sentinel.execute(fn, await sentinel.getClientLease());
}

Prevention

When it happens

Trigger: Issuing a read-only command against a Sentinel client configured with replicaPoolSize > 0 when no replica client exists at that instant — typically right after a failover, during the initial connect window before replicas connect, or when the sentinel reports zero replicas.

Common situations: Spin-up race where reads fire before observe/transform wires up replicas; a deployment with no replicas but replicaPoolSize set; replicas all marked sdown so none got connected.

Related errors

AI-assisted analysis of redis/node-redis@bb5beb5657 (2026-08-03). Data as JSON: /data/errors/11406471f1c58954.json. Report an issue: GitHub.