redis/redis-py · error · RedisError

MONITOR failed: {response}

Error message

MONITOR failed: {response}

What it means

Raised in `_start_monitor` after the client sends MONITOR and reads the server reply: if the reply is not the Redis "OK" status (bool_ok fails), the server rejected or did not acknowledge the MONITOR command. The library throws RedisError because MONITOR is a special server-side mode that must be explicitly acknowledged before the client can begin reading the streamed command stream via `listen()`/`next_command()`.

Source

Thrown at redis/client.py:1098

            "db": int(db_id),
            "client_address": client_address,
            "client_port": client_port,
            "client_type": client_type,
            "command": command,
        }

    def listen(self):
        """Listen for commands coming to the server."""
        while True:
            yield self.next_command()

    def _start_monitor(self):
        self.connection.send_command("MONITOR")
        # check that monitor returns 'OK', but don't return it to user
        response = self.connection.read_response()

        if not bool_ok(response):
            raise RedisError(f"MONITOR failed: {response}")


class PubSub:
    """
    PubSub provides publish, subscribe and listen support to Redis channels.

    After subscribing to one or more channels, the listen() method will block
    until a message arrives on one of the subscribed channels. That message
    will be returned and it's safe to start listening again.
    """

    PUBLISH_MESSAGE_TYPES = ("message", "pmessage", "smessage")
    UNSUBSCRIBE_MESSAGE_TYPES = ("unsubscribe", "punsubscribe", "sunsubscribe")
    HEALTH_CHECK_MESSAGE = "redis-py-health-check"

    def __init__(
        self,
        connection_pool,

View on GitHub (pinned to da03cdc7e8)

Solutions

  1. Grant the connecting user the necessary ACL permissions (e.g. `ACL SETUSER <user> on +@all -@dangerous ~*` or explicitly allow MONITOR) or connect with a user that has admin rights.
  2. Verify the target is a standalone Redis that permits MONITOR; proxies/managed offerings may reject it — use a self-managed Redis or the provider's approved diagnostics instead.
  3. Inspect the embedded `{response}` value to see the server's exact refusal reason and resolve that underlying error (AUTH, ACL, BUSYLOAD, etc.).
  4. If the server only intermittently rejects MONITOR, retry after confirming server health and that no other session is already in a state that blocks it.

Example fix

# before
client = redis.Redis(username='app', password='secret')
m = client.monitor()  # raises: MONITOR failed: NOPERM ...

# after (grant monitoring permission to the user)
# ACL SETUSER app resetkeys on +@all ~*
client = redis.Redis(username='app', password='secret')
m = client.monitor()
Defensive patterns

Strategy: try-catch

Validate before calling

from redis.exceptions import RedisError
# Before calling monitor(), confirm the server is reachable and the user likely has permission
try:
    client.ping()
except RedisError:
    raise

Try / catch

from redis.exceptions import RedisError
try:
    mon = client.monitor()
    for cmd in mon.listen():
        ...
except RedisError as e:
    if 'MONITOR failed' in str(e):
        # server rejected MONITOR — check ACL/server type
        log.warning('monitor unavailable: %s', e)
    else:
        raise

Prevention

When it happens

Trigger: Calling `client.monitor()` (or directly instantiating the Monitor thread) against a Redis server that refuses MONITOR. This happens when the authenticated user lacks the monitoring ACL permission, when the server is a read-only replica configured to deny MONITOR, or when the connection received a non-OK framed reply (e.g. an error string or an authorization denial). The reply content is interpolated into the message for diagnostics.

Common situations: Using an ACL-restricted user without `+@admin`/monitoring rights; pointing the client at a proxy or managed Redis (Redis Cloud, AWS ElastiCache) that disables MONITOR; running MONITOR against a Sentinel or cluster node in a topology where the command is forbidden; corrupted protocol state causing a non-status reply.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/a97db608a55d5a13.json. Report an issue: GitHub.