🚨 RabbitMQ Error Guide: 'STREAM_NOT_AVAILABLE' — Fix Stream Leader Unavailability

Overview

A RabbitMQ Streams client tried to publish to or consume from a stream, and the broker replied that the stream has no available leader to serve the request:

STREAM_NOT_AVAILABLE (code 15): stream 'events' is not available

Streams use a Raft-based replication group like quorum queues. STREAM_NOT_AVAILABLE means the stream coordinator cannot hand the client a live leader — because no leader is currently elected, the hosting node is down, or the stream plugin/listener isn’t serving on the node the client reached.

Symptoms

• Stream producers/consumers fail on connect or on declare/subscribe with STREAM_NOT_AVAILABLE.
• The error clears and returns as leadership flaps during node restarts or network blips.
• A stream works from one node’s perspective but not another.
• New streams can’t be declared right after a node comes up (metadata not yet warm).
• Clients using the binary stream protocol (port 5552) can’t establish a route to the leader.

Common Root Causes

• Leader node down — the node hosting the stream leader is stopped or crashed and no replica has been elected leader yet.
• Lost replica quorum — too few stream members are online to elect a leader (majority of the replica set unavailable).
• Stream plugin not enabled — rabbitmq_stream (and rabbitmq_stream_management) isn’t enabled on the node the client hit.
• Stream listener/port unreachable — port 5552 (or TLS 5551) isn’t listening or is blocked by a firewall/LB.
• Metadata not converged — right after startup the stream coordinator hasn’t finished electing/advertising a leader.
• advertised host/port misconfig — the client is redirected to a leader address it can’t reach.

Diagnostic Workflow

Confirm the stream plugin is enabled and the listener is up:

rabbitmq-plugins list -e | grep stream
rabbitmq-diagnostics listeners | grep -i stream

Check overall cluster health and which nodes are running:

rabbitmq-diagnostics cluster_status
rabbitmq-diagnostics check_running

Inspect the stream’s members, leader, and online replicas:

rabbitmqctl list_stream_connections 2>/dev/null
rabbitmqctl list_queues name type leader members online -p / | grep -i stream

Look for coordinator/leader election events in the log:

grep -iE 'stream|coordinator|leader|osiris' \
  /var/log/rabbitmq/rabbit@$(hostname -s).log | tail -n 50

Verify the stream port is reachable from the client network:

nc -zv broker-host 5552

Example Root Cause Analysis

A stream consumer began failing with STREAM_NOT_AVAILABLE for stream events during a rolling restart. rabbitmq-diagnostics cluster_status showed node rabbit@node2 was still down mid-restart.

rabbitmqctl list_queues name type leader members online showed stream events had 3 members but only 1 online, with no leader listed — the leader had lived on node2, and with a majority of replicas offline no new leader could be elected. The coordinator therefore reported the stream unavailable.

Bringing node2 back and waiting for the replicas to rejoin restored quorum; a leader was elected and the error cleared:

rabbitmqctl start_app                      # on the recovering node
rabbitmqctl list_queues name type leader online -p /

Root cause: transient loss of replica quorum during the restart left the stream with no electable leader. The fix was restoring member availability, not touching the client.

Prevention Best Practices

• Give each stream an odd replica count (3 or 5) across fault domains so a single node loss keeps a majority.
• Roll restarts one node at a time and wait for streams to regain a leader (online == members) before proceeding.
• Enable rabbitmq_stream on every node clients may connect to, and confirm port 5552/5551 is open end to end.
• Set correct advertised_host/advertised_port so clients are redirected to reachable leader addresses.
• Have clients retry STREAM_NOT_AVAILABLE with backoff — leadership changes are transient.

Quick Command Reference

rabbitmq-plugins list -e | grep stream           # is the stream plugin on
rabbitmq-diagnostics listeners | grep -i stream  # is port 5552 listening
rabbitmq-diagnostics cluster_status              # which nodes are up
rabbitmqctl list_queues name type leader members online   # stream leader/replicas
nc -zv broker-host 5552                          # stream port reachability

Conclusion

STREAM_NOT_AVAILABLE means the stream coordinator can’t give the client a live leader — usually because the leader node is down, replica quorum is lost, or the stream plugin/port isn’t serving on the node reached. Check the plugin and listener, confirm cluster membership and the stream’s online replicas, and restore quorum. Size streams with an odd replica count across fault domains and have clients retry with backoff so transient leader elections don’t surface as hard failures.