redis/jedis · error · JedisConnectionException

Failed to check buffer on connection.

Error message

Failed to check buffer on connection.

What it means

This connection check probes whether buffered bytes are pending on the socket (inputStream.available()) and consumes any pushed messages. An IOException during this check indicates the socket is dead or unreadable, so the connection is marked broken and a JedisConnectionException is thrown.

Solutions

1. Treat the exception as a stale-connection signal: drop the connection and retry the operation on a new one.
2. Enable connection pool eviction/test-on-borrow style health checks (or keepalive) to prune stale sockets.
3. Configure TCP keepalive and reasonable socket timeouts to detect dead peers faster.
4. Ensure RESP3 push handling is set up correctly if this fires during push processing.

Example fix

// before
Jedis j = pool.getResource(); // stale pooled conn may throw here
// after
jedisPool with testWhileIdle/minEvictableIdleTime configured; catch JedisConnectionException and retry once with a fresh resource

// prune stale pooled connections
try (Jedis j = pool.getResource()) { j.ping(); } // before critical work

try {
  return jedis.get(key);
} catch (JedisConnectionException e) {
  return freshJedis().get(key); // one retry on a new connection
}

When it happens

Trigger: Checking the input buffer on a connection whose socket was closed/reset by the peer (server restart, failover, idle timeout, network partition) — invoked from the public Connection health-check path.

Common situations: Redis server restarted between commands; sentinel/cluster failover closed old connections; NAT or LB silently dropping idle TCP connections; long-lived pooled connections that went stale.

Related errors

• Failed to create socket.
• Initialization failed due to initialization policy
• Initialization failed due to initialization policy
• All configured databases are unhealthy. Cannot initialize…
• No healthy database available after initialization policy…

AI-assisted analysis of redis/jedis@6dac31d4c2 (2026-09-08). Data as JSON: /api/errors/fec391f1806ef4a6. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/Connection.java:809

      // leave the stream position indeterminate.
      throw markBroken(exc);
    } catch (Error err) {
      throw markBroken(err);
    }
  }

  protected void readPushesWithCheckingBroken() {
    if (broken) {
      throw new JedisConnectionException("Attempting to read from a broken connection.", brokenCause);
    }

    try {
      applyCurrentTimeout();
      if (inputStream.available() > 0) {
        protocolReadPushes(inputStream, pushConsumers);
      }
    } catch (IOException e) {
      throw markBroken(new JedisConnectionException("Failed to check buffer on connection.", e));
    } catch (RuntimeException exc) {
      throw markBroken(exc);
    } catch (Error err) {
      throw markBroken(err);
    }
  }

  public List<Object> getMany(final int count) {
    flush();
    final List<Object> responses = new ArrayList<>(count);
    for (int i = 0; i < count; i++) {
      try {
        responses.add(readProtocolWithCheckingBroken());
      } catch (JedisDataException e) {
        responses.add(e);
      }
    }
    return responses;

View on GitHub (pinned to 6dac31d4c2)