redis/redis-py · error · NotImplementedError

FAILOVER is intentionally not implemented in the client.

Error message

FAILOVER is intentionally not implemented in the client.

What it means

Raised by failover() (redis/commands/core.py:2301) which is a stub that unconditionally raises NotImplementedError. FAILOVER initiates a replication failover to a replica and is a long-blocking, topology-altering operation better orchestrated by sentinel/cluster tooling than a generic client method, so the library refuses it. No arguments are accepted.

Solutions

Use redis.Sentinel for managed failover, or redis.RedisCluster for cluster topology
If you must trigger it directly: r.execute_command("FAILOVER", *opts) with explicit TIMEOUT/FORCE/TO as needed
Prefer orchestrating failover at the infrastructure/sentinel layer rather than from app code

Example fix

# before
r.failover()
# after
r.execute_command("FAILOVER")  # if a manual failover is truly required

Defensive patterns

Strategy: fallback

Validate before calling

# failover() is intentionally unimplemented; use execute_command or sentinel
def manual_failover(r, **opts):
    pieces = []
    for k, v in opts.items():
        pieces.extend([k.upper(), v])
    return r.execute_command("FAILOVER", *pieces)

Try / catch

try:
    r.failover()
except NotImplementedError:
    r.execute_command("FAILOVER")

Prevention

Prefer Sentinel/Cluster orchestration for failover over app-level calls.
If manual failover is required, wrap execute_command('FAILOVER',...).
Document that the client method is a permanent stub.

When it happens

Trigger: Calling r.failover(). Any call raises immediately.

Common situations: Manually promoting a replica from application code; assuming the client mirrors every admin command.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/be428b063b84fa7f. Report an issue: GitHub.

Appendix: source

Thrown at redis/commands/core.py:2301

        return self.execute_command(
            "WAITAOF", num_local, num_replicas, timeout, **kwargs
        )

    def hello(self):
        """
        This function throws a NotImplementedError since it is intentionally
        not supported.
        """
        raise NotImplementedError(
            "HELLO is intentionally not implemented in the client."
        )

    def failover(self):
        """
        This function throws a NotImplementedError since it is intentionally
        not supported.
        """
        raise NotImplementedError(
            "FAILOVER is intentionally not implemented in the client."
        )

    @overload
    def hotkeys_start(
        self: SyncClientProtocol,
        metrics: List[HotkeysMetricsTypes],
        count: int | None = None,
        duration: int | None = None,
        sample_ratio: int | None = None,
        slots: List[int] | None = None,
        **kwargs,
    ) -> bytes | str: ...

    @overload
    def hotkeys_start(
        self: AsyncClientProtocol,
        metrics: List[HotkeysMetricsTypes],

View on GitHub (pinned to 6a6b581b48)