Troubleshooting Common Redis Pub/Sub Configuration Issues.

Redis Pub/Sub is simple enough that teams often treat it like a tiny message broker they do not need to operate. A publisher calls PUBLISH, subscribers receive messages, and everything feels instant.

The trouble starts when real networks, slow clients, reconnects, and shared Redis instances get involved. Pub/Sub has no message history, no acknowledgments, and no retry queue. It is a live broadcast mechanism. If a subscriber is gone, the message is gone for that subscriber. If a subscriber is connected but cannot read fast enough, Redis has to hold pending output for that client until a configured limit disconnects it.

That makes Redis Pub/Sub great for cache invalidation, presence updates, live dashboards, and "latest value" notifications. It is a poor fit for workflows where every message must be processed exactly once or replayed after an outage. For that, look at Redis Streams, RabbitMQ, Kafka, or another broker with delivery tracking.

Symptom: memory grows while Pub/Sub traffic is high

The most common Pub/Sub failure is a slow subscriber. The publisher is fine. Redis is fine at first. One consumer is behind because its process is paused, its network is slow, or it does expensive work inside the message handler. Redis keeps writing messages to that client's output buffer. If the buffer is allowed to grow without a useful limit, memory pressure spreads from one bad subscriber to the whole instance.

Check clients:

redis-cli CLIENT LIST

Look for clients with Pub/Sub commands and large output memory:

id=88 addr=10.0.4.12:51244 flags=P db=0 sub=3 psub=0 omem=13421772 obl=128 oll=64 cmd=subscribe

Useful fields:

• flags=P indicates a Pub/Sub client.
• sub and psub show channel and pattern subscription counts.
• omem is output buffer memory in bytes.
• obl and oll show output buffer backlog details.
• cmd=subscribe or cmd=psubscribe confirms what the client is doing.

Do not panic over idle for subscribers. A Pub/Sub connection may sit idle from the command point of view while still receiving pushed messages.

Fix slow consumers with output buffer limits

Redis gives Pub/Sub clients their own output buffer limit class:

client-output-buffer-limit pubsub 32mb 8mb 60

Read that as:

• Disconnect immediately if a Pub/Sub client's output buffer reaches 32 MB.
• Disconnect if it stays above 8 MB for 60 seconds.

The exact numbers should match your traffic and client behavior. The common mistake is setting the limit to 0 0 0 because disconnects are annoying during testing. That removes the safety rail. In production, a disconnect is usually better than letting one stuck subscriber consume memory until Redis becomes unstable.

After changing redis.conf, reload or restart according to your deployment process. You can also inspect the live value:

redis-cli CONFIG GET client-output-buffer-limit

If you use a managed Redis service, this setting may be exposed through the provider's parameter group or configuration UI rather than direct file editing.

Symptom: subscribers connect but receive nothing

Start with the simplest possible test. Open one terminal:

redis-cli SUBSCRIBE test.channel

Open another:

redis-cli PUBLISH test.channel hello

If that works from the Redis host but not from your application, you probably have a client-side or network issue. If it fails everywhere, check authentication, ACLs, cluster routing, and the actual channel name.

Channel names are exact byte strings. events.user, events:User, and events:user are different channels. In larger systems, I prefer constants or a small channel naming module over hand-typed strings scattered across services.

Pattern subscriptions add another source of confusion:

PSUBSCRIBE events:*

This matches events:user.created, but not prod:events:user.created. If your application prefixes environment names, include the prefix in the pattern.

Authentication and ACL problems

Modern Redis deployments often use ACL users instead of one shared requirepass password. A Pub/Sub client needs permission to connect, authenticate, subscribe to the channel pattern, and sometimes publish.

A quick CLI check:

redis-cli -u redis://app-user:[email protected]:6379 PING
redis-cli -u redis://app-user:[email protected]:6379 SUBSCRIBE events:test

Common authentication symptoms:

• NOAUTH Authentication required: the client sent a command before authenticating.
• WRONGPASS invalid username-password pair: wrong password, wrong user, or a rotated secret not deployed everywhere.
• NOPERM this user has no permissions: the user authenticated but lacks command or channel permissions.

With ACLs, channel permissions are separate from key permissions. A user can be allowed to run normal key commands but not subscribe to the channels you expect. Review the configured user:

redis-cli ACL GETUSER app-user

Do not paste production secrets into shell history while testing. Use environment variables or a temporary credential when possible.

Do not share Pub/Sub connections with normal commands

Once a connection enters subscribed mode, it is not a normal Redis command connection anymore. It receives pushed messages and can only issue subscription-related commands such as SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE, PING, RESET, or quit-style commands depending on the client and Redis version.

If you borrow a connection from a general pool and call SUBSCRIBE, that pooled connection is effectively no longer available for GET, SET, or other ordinary commands. The result can look like random application timeouts because the pool slowly fills with connections stuck in subscriber mode.

Use separate connections:

• One normal client or pool for regular Redis commands.
• One long-lived subscriber connection per subscriber process or thread.
• One separate publisher connection if your client library recommends it.

Many client libraries provide a duplicate() or new connection method for this reason. Use it. Do not guess that the pool will sort it out.

Reconnect behavior matters

Pub/Sub does not replay missed messages after reconnect. If a subscriber drops for 30 seconds, every message published during that window is missed by that subscriber.

That is acceptable for cache invalidation only if your application has a fallback. For example, a service that misses an invalidation event should still have TTLs, version checks, or a way to rebuild from the source database. Without a fallback, a single network blip can leave stale local cache entries around for too long.

On reconnect, make sure the client resubscribes to all channels and patterns. Some libraries do this automatically. Others require you to re-register handlers after reconnect. Test this by killing the subscriber connection:

redis-cli CLIENT LIST | grep subscribe
redis-cli CLIENT KILL ID <client-id>

Then publish a test message and confirm the application receives it after reconnecting.

High fan-out can become CPU and network pressure

PUBLISH work grows with the number of matching subscribers and patterns. A channel with thousands of subscribers means Redis has to push the message thousands of times. That may still be fine, but it is not free.

Watch:

redis-cli INFO stats
redis-cli PUBSUB NUMSUB events:test
redis-cli PUBSUB NUMPAT

PUBSUB NUMSUB helps confirm whether a channel has the subscriber count you think it has. PUBSUB NUMPAT is useful because broad pattern subscriptions can surprise you. A handful of services using PSUBSCRIBE * or PSUBSCRIBE events:* can receive far more traffic than intended.

If Pub/Sub traffic is important and high volume, isolate it. A dedicated Redis instance for Pub/Sub protects your cache and session store from subscriber buffer problems and broadcast spikes. The dedicated instance can have configuration tuned for Pub/Sub, shorter persistence concerns, and monitoring focused on clients and network output.

Keep message handlers short

A subscriber should read the message, do minimal validation, and hand work to something else. If the handler calls a database, makes an HTTP request, renders a template, or performs a long computation before reading the next message, it can become the slow consumer you are trying to avoid.

Better shape:

Redis message -> lightweight handler -> local queue -> worker pool

The local queue may be an in-process queue, a thread pool, an async task queue, or a durable broker if the work must survive process restarts. The key idea is that reading from Redis should not wait on the slowest downstream dependency.

If the work must be reliable, Pub/Sub is the wrong primitive. Redis Streams with consumer groups gives you pending entries and acknowledgments. A dedicated broker may be better if you need dead-letter queues, delayed retries, priorities, or long retention.

A practical troubleshooting checklist

When Pub/Sub looks unhealthy, I usually work in this order:

1. Confirm the channel manually with SUBSCRIBE and PUBLISH.
2. Check CLIENT LIST for Pub/Sub clients with high omem.
3. Inspect client-output-buffer-limit pubsub.
4. Verify authentication and ACL channel permissions.
5. Confirm subscribers use dedicated connections.
6. Kill a subscriber connection and verify reconnect plus resubscribe behavior.
7. Check PUBSUB NUMSUB and PUBSUB NUMPAT for unexpected fan-out.
8. Decide whether the workload actually needs Streams or a dedicated broker.

Redis Pub/Sub is reliable only in the sense that it does exactly what it promises: live message broadcast to currently connected subscribers. Most production incidents come from expecting it to behave like a durable queue. Configure buffer limits, isolate heavy traffic, and design subscribers as if messages can be missed, because sometimes they can.

Example incident: one dashboard slows the cache

Picture a Redis instance used for ordinary cache keys and a small Pub/Sub channel called metrics:live. At first, only an internal dashboard subscribes. Months later, several browser gateway processes subscribe too, and one of them starts sending updates over slow WebSocket connections. Redis does not know that the downstream browser is slow. It only sees a subscriber connection that is not reading fast enough.

The first symptom may not mention Pub/Sub at all. Application requests that use normal GET and SET calls start timing out. Memory climbs. The Redis host looks busy, but SLOWLOG does not show an obvious expensive command.

The useful clue is in CLIENT LIST:

flags=P sub=1 omem=25165824 cmd=subscribe

That tells you a Pub/Sub client has a large output buffer. If the configured hard limit is 32 MB, that client is close to being disconnected. If the limit is disabled, Redis may keep buffering until the whole instance is under memory pressure.

The fix is not just raising the limit. Raising it may hide the problem and allow a worse memory spike next time. A better response is:

1. Identify the subscriber process from addr, name, or client metadata.
2. Kill the worst subscriber if memory is at risk.
3. Add or tighten client-output-buffer-limit pubsub.
4. Move slow downstream delivery into an internal queue outside the Redis read loop.
5. Consider moving high-volume Pub/Sub to a dedicated Redis instance.

Client names make this much easier. Many Redis libraries let you set a connection name. Use names such as web-1:pubsub-cache-invalidations or dashboard:metrics-live so CLIENT LIST points to the owner instead of only showing an IP and port.

CLIENT SETNAME dashboard:metrics-live

That small bit of hygiene turns a vague memory incident into a direct conversation with the team that owns the subscriber.