What causes "payload must be String or byte[]" in redis/jedis?

Convert the payload to a String (e.g. String.valueOf(value)) before passing it

redis/jedis · error · IllegalArgumentException

payload must be String or byte[]

Error message

payload must be String or byte[]

What it means

CompareCondition's private constructor validates that its payload is either a String or a byte[]; anything else triggers this IllegalArgumentException. The library only knows how to encode those two payload types for compare conditions, so other object types are rejected at construction time.

Solutions

Convert the payload to a String (e.g. String.valueOf(value)) before passing it
Or convert to byte[] (use SafeEncoder.encode or Protocol.toByteArray for numbers)
Add a type check at the call site to fail fast with a clearer message

Example fix

// before
CompareCondition cond = CompareCondition.equals(42);
// after
CompareCondition cond = CompareCondition.equals(String.valueOf(42));

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(payload instanceof String) && !(payload instanceof byte[])) { throw new IllegalArgumentException("payload must be String or byte[]"); }

Type guard

boolean isValidPayload(Object p) { return p instanceof String || p instanceof byte[]; }

Try / catch

try {
  CompareCondition c = CompareCondition.equals(value);
} catch (IllegalArgumentException e) {
  // convert value to String/byte[] and retry
}

Prevention

Always pass String or byte[] payloads to compare conditions
Convert numbers with String.valueOf or Protocol.toByteArray
Validate payload type at your API boundary

When it happens

Trigger: Calling a CompareCondition factory or constructor with a payload that is neither String nor byte[], e.g. an Integer, Long, Double, byte-buffer wrapper, or a custom object.

Common situations: Passing numeric values boxed as Integer/Long instead of converting to String; passing a ByteBuffer instead of byte[]; generic code that forwards Object payloads without knowing the accepted types.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/util/CompareCondition.java:52

    private final Keyword keyword;

    Condition(Keyword keyword) {
      this.keyword = keyword;
    }

    /** The protocol keyword to emit for this condition. */
    public Keyword getKeyword() {
      return keyword;
    }
  }

  private final Condition condition;
  private final Object payload; // String or byte[]

  private CompareCondition(Condition condition, Object payload) {
    if (!(payload instanceof String) && !(payload instanceof byte[])) {
      throw new IllegalArgumentException("payload must be String or byte[]");
    }
    this.condition = condition;
    this.payload = payload;
  }

  // Factory methods: value-based
  public static CompareCondition valueEq(String value) {
    JedisAsserts.notNull(value, "value must not be null");
    return new CompareCondition(Condition.VALUE_EQUAL, value);
  }

  public static CompareCondition valueNe(String value) {
    JedisAsserts.notNull(value, "value must not be null");
    return new CompareCondition(Condition.VALUE_NOT_EQUAL, value);
  }

  public static CompareCondition valueEq(byte[] value) {
    JedisAsserts.notNull(value, "value must not be null");

View on GitHub (pinned to 6dac31d4c2)