What causes "MONITOR failed: {response}" in redis/redis-py?

Grant the MONITOR permission to the user: `ACL SETUSER on >password ~* +monitor`.

redis/redis-py · error · RedisError

MONITOR failed

Error message

MONITOR failed: {response}

What it means

Raised as RedisError in Monitor._start_monitor after sending the MONITOR command if the server response is not the OK status (bool_ok). MONITOR puts the connection into a special server-side mode that streams every command; if the server rejects it (e.g. ACL denial, or a non-standard reply), the response is included in the message for diagnosis. The Monitor object cannot function without entering monitor mode.

Solutions

Grant the MONITOR permission to the user: `ACL SETUSER <user> on >password ~* +monitor`.
Use an admin-capable user for the monitor connection.
Check the {response} value in the error to see the exact server reply and act on it.
If MONITOR is disabled by your provider, use a different observability mechanism (SLOWLOG, etc.).

Example fix

# before: user lacks MONITOR permission
mon = r.monitor()
# server denies -> RedisError: MONITOR failed: ...
# after: grant permission
# redis-cli: ACL SETUSER appuser on >pass ~* +monitor
mon = r.monitor()

Defensive patterns

Strategy: try-catch

Validate before calling

info = await client.acl_getuser() if False else None  # placeholder
# verify the user has +monitor via ACL GETUSER before calling monitor()

Try / catch

from redis.exceptions import RedisError
try:
    mon = client.monitor()
    await mon.next_command()
except RedisError as e:
    if "MONITOR failed" in str(e):
        logger.error("MONITOR denied: %s; check ACL +monitor permission", e)
    raise

Prevention

Grant the +monitor ACL permission to the monitoring user.
Inspect the server's MONITOR reply in the error to diagnose non-OK responses.

When it happens

Trigger: Calling client.monitor() then next_command()/listen() (which lazily calls _start_monitor) against a server that does not reply OK to MONITOR. Commonly an ACL/permission denial (NOPERM), or an error reply from a proxy/managed Redis that disallows MONITOR.

Common situations: Connecting with a user that lacks the MONITOR privilege (ACL). Using a managed Redis (some Redis Cloud / proxy configs) where MONITOR is disabled. A server that returned an error string instead of OK.

Related errors

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

Appendix: 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 6a6b581b48)