redis/jedis · error · JedisException

Could not return the broken resource to the pool

Error message

Could not return the broken resource to the pool

What it means

Pool.returnBrokenResource(resource) invalidates a defective connection via commons-pool2 invalidateObject. If invalidation throws, it is wrapped in JedisException("Could not return the broken resource to the pool"). The broken connection could not be discarded cleanly.

Solutions

1. Ensure returnBrokenResource is called at most once per resource — use a flag or structure so catch and finally don't both run it.
2. Check pool lifecycle: don't return/invalidate resources after destroy().
3. Inspect getCause() for the underlying factory/socket failure.
4. Prefer try-with-resources on Jedis, which routes broken resources correctly.

Example fix

// before
} catch (JedisException e) {
  pool.returnBrokenResource(jedis);
} finally {
  pool.returnBrokenResource(jedis); // second invalidate -> throws
}
// after
} catch (JedisException e) {
  pool.returnBrokenResource(jedis);
} finally {
  pool.returnResource(jedis); // invalidateObject is idempotent-safe in pool2; or guard with boolean flag
}

try {
  pool.returnBrokenResource(resource);
} catch (JedisException e) {
  log.warn("Failed to invalidate broken resource", e.getCause());
}

When it happens

Trigger: Calling returnBrokenResource with an object already invalidated, not borrowed from this pool, or borrowed after destroy(); underlying factory destroyObject throwing (e.g. socket close error on a dead connection).

Common situations: Error-handling paths that call returnBrokenResource after the pool was already shut down; marking the same broken connection broken twice (e.g. in both a catch block and finally).

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Could not destroy the pool
• Could not get a resource from the pool
• Could not return the resource to the pool
• Error trying to add idle objects
• Resource is returned to the pool as broken

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/util/Pool.java:64

  public void returnResource(final T resource) {
    if (resource == null) {
      return;
    }
    try {
      super.returnObject(resource);
    } catch (RuntimeException e) {
      throw new JedisException("Could not return the resource to the pool", e);
    }
  }

  public void returnBrokenResource(final T resource) {
    if (resource == null) {
      return;
    }
    try {
      super.invalidateObject(resource);
    } catch (Exception e) {
      throw new JedisException("Could not return the broken resource to the pool", e);
    }
  }

  @Override
  public void addObjects(int count) {
    try {
      for (int i = 0; i < count; i++) {
        addObject();
      }
    } catch (Exception e) {
      throw new JedisException("Error trying to add idle objects", e);
    }
  }
}

View on GitHub (pinned to 6dac31d4c2)