redis/redis-py · error · RedisError

Channel ' ' has no handler registered

Error message

Channel '{channel}' has no handler registered

What it means

KeyspaceNotifications._validate_all_handlers (redis/keyspace_notifications.py:1725, standalone) raises RedisError if any exact-channel subscription in the underlying PubSub has a None handler. Validation runs when you call run_in_thread, because the worker thread relies entirely on registered handlers to dispatch messages. A channel subscribed without a handler cannot be dispatched and is treated as a setup bug.

Solutions

1. Register a handler for every channel before calling run_in_thread: notifications.subscribe(KeyspaceChannel('events'), handler=my_handler).
2. If you want to consume messages manually (no handler), use get_message()/listen() instead of run_in_thread.
3. Confirm no subscribe call omitted or nulled the handler.

Example fix

// before
notifications.subscribe(KeyspaceChannel('events'))
notifications.run_in_thread(poll_timeout=0.1)
// after
notifications.subscribe(KeyspaceChannel('events'), handler=on_event)
notifications.run_in_thread(poll_timeout=0.1)

def all_channels_have_handler(ksn) -> bool:
    return all(h is not None for _, h in ksn._pubsub.channels.items())

When it happens

Trigger: notifications.subscribe(KeyspaceChannel('events'), handler=None) or subscribe(... ) omitting handler, then notifications.run_in_thread(...). Also if a subscribe was performed with handler but it was later cleared/reset to None before run_in_thread.

Common situations: Subscribing to listen via get_message/listen (handler-less, which is valid) and then switching to run_in_thread without re-subscribing with handlers; a typo/omission in the handler kwarg; copying a listen()-based example into a run_in_thread flow.

Related errors

• Pattern ' ' has no handler registered
• Channel: ' ' has no handler registered
• Failed to subscribe to cluster nodes
• Pattern: ' ' has no handler registered
• A non health check response was cleaned by execute_command

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

Appendix: source

Thrown at redis/keyspace_notifications.py:1725

        Example:
            >>> for notification in ksn.listen():
            ...     print(f"{notification.key}: {notification.event_type}")
        """
        while self.subscribed:
            notification = self.get_message(timeout=1.0)
            if notification is not None:
                yield notification

    @property
    def subscribed(self) -> bool:
        """Check if there are any active subscriptions and not closed."""
        return not self._closed and self._pubsub.subscribed

    def _validate_all_handlers(self) -> None:
        """Raise if any subscription in the underlying PubSub lacks a handler."""
        for channel, handler in self._pubsub.channels.items():
            if handler is None:
                raise RedisError(f"Channel '{channel}' has no handler registered")
        for pattern, handler in self._pubsub.patterns.items():
            if handler is None:
                raise RedisError(f"Pattern '{pattern}' has no handler registered")

    def close(self):
        """Close the pubsub connection and clean up resources."""
        self._closed = True
        try:
            self._pubsub.close()
        except Exception:
            pass


# =============================================================================
# Cluster-Aware Keyspace Notification Manager
# =============================================================================

View on GitHub (pinned to 6a6b581b48)