redis/jedis · error · IllegalStateException

Cannot use Jedis when in Pipeline. Please use Pipeline or…

Error message

Cannot use Jedis when in Pipeline. Please use Pipeline or reset jedis state.

What it means

When a Jedis instance has pipelined commands whose responses have not been read back, direct commands on the instance would desynchronize request/response ordering. checkIsInMultiOrPipeline throws IllegalStateException when pipeline != null and hasPipelinedResponse() is true. You must sync the pipeline or reset state before issuing standalone commands.

Solutions

Call pipeline.sync() (or syncAndReturnAll()) before issuing direct commands on jedis
Close the pipeline (try-with-resources on Pipeline) so state is cleaned on all paths
Call jedis.resetState() to discard pending pipelined responses if they are not needed
Use a separate connection from the pool for administrative commands

Example fix

// before
Pipeline p = jedis.pipelined();
p.set("k", "v");
jedis.ping(); // IllegalStateException: in Pipeline
// after
Pipeline p = jedis.pipelined();
p.set("k", "v");
p.sync();
jedis.ping(); // OK

Defensive patterns

Strategy: try-catch

Try / catch

try {
  jedis.flushDB();
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Cannot use Jedis when in Pipeline")) {
    pipeline.sync();
    jedis.flushDB();
  } else throw e;
}

Prevention

Always call pipeline.sync()/close() in a finally block or use try-with-resources
Do not interleave direct commands while a pipeline has buffered responses
Return pooled Jedis instances only after the pipeline is synced

When it happens

Trigger: Calling ping/select/swapDB/flushDB/flushAll/copy (or any guarded command) on a Jedis after jedis.pipelined() was used and commands are still buffered (no sync/close yet).

Common situations: Interleaving administrative commands into a batch write loop that pipelines; exception paths that skip pipelining.sync() leaving responses pending; reusing a pooled Jedis instance that was returned with a live pipeline.

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

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/Jedis.java:434

      }
    };
    return transaction;
  }

  // Legacy
  public Pipeline pipelined() {
    pipeline = new Pipeline(this);
    return pipeline;
  }

  // Legacy
  protected void checkIsInMultiOrPipeline() {
//    if (connection.isInMulti()) {
    if (transaction != null) {
      throw new IllegalStateException(
          "Cannot use Jedis when in Multi. Please use Transaction or reset jedis state.");
    } else if (pipeline != null && pipeline.hasPipelinedResponse()) {
      throw new IllegalStateException(
          "Cannot use Jedis when in Pipeline. Please use Pipeline or reset jedis state.");
    }
  }

  public int getDB() {
    return this.db;
  }

  /**
   * @return <code>PONG</code>
   */
  @Override
  public String ping() {
    checkIsInMultiOrPipeline();
    connection.sendCommand(Command.PING);
    return connection.getStatusCodeReply();
  }

View on GitHub (pinned to 6dac31d4c2)