redis/jedis · error · IllegalArgumentException

is not a valid ZRANGE type argument.

Error message

${by} is not a valid ZRANGE type argument.

What it means

The private ZRangeParams constructor only accepts ZRANGEBYSCORE (BYSCORE) or ZRANGEBYLEX (BYLEX) as the range type; any other keyword (or a null handled as a bad name) produces this IllegalArgumentException. It protects against constructing ZRangeParams with an unsupported range semantics.

Solutions

1. Use the public factories: ZRangeParams.zRangeByScoreParams(min, max), zRangeByLexParams(min, max), or zRangeByRankParams(min, max).
2. Fix the code that passes a non-BYSCORE/BYLEX keyword into the constructor.
3. Check the Jedis version's supported ZRANGE argument types if upgrading changed behavior.

Example fix

// before
ZRangeParams params = new ZRangeParams(Keyword.BYRANK, min, max);
// after
ZRangeParams params = ZRangeParams.zRangeByRankParams(0, -1);

if (by != Keyword.BYSCORE && by != Keyword.BYLEX) throw new IllegalArgumentException("Use byScore or byLex for ZRangeParams");

boolean isAllowedZRangeBy(Keyword by) { return by == Keyword.BYSCORE || by == Keyword.BYLEX; }

try {
  return new ZRangeParams(by, min, max);
} catch (IllegalArgumentException e) {
  return ZRangeParams.zRangeByRankParams(0, -1);
}

When it happens

Trigger: Constructing ZRangeParams via a static factory or reflection path that passes a different Keyword (e.g. BYRANK or a custom Rawable keyword) instead of byScore()/byLex()/byRank() entry points.

Common situations: Writing generic param-building code that forwards an arbitrary Keyword into ZRangeParams; misusing internal constructors after an upgrade changed the allowed set; building params manually instead of using zRangeParams helpers.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• LIMIT must be non-negative
• IDMP-DURATION must be between 1 and 86400 seconds
• IDMP-MAXSIZE must be between 1 and 10000
• start, end and count must be set.
• Unsupported key type

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/params/ZRangeParams.java:60

  public static ZRangeParams zrangeParams(long min, long max) {
    return new ZRangeParams(min, max);
  }

  public ZRangeParams(double min, double max) {
    this.by = BYSCORE;
    this.min = from(min);
    this.max = from(max);
  }

  public static ZRangeParams zrangeByScoreParams(double min, double max) {
    return new ZRangeParams(min, max);
  }

  private ZRangeParams(Keyword by, Rawable min, Rawable max) {
    if (by == null || by == BYSCORE || by == BYLEX) {
      // ok
    } else {
      throw new IllegalArgumentException(by.name() + " is not a valid ZRANGE type argument.");
    }
    this.by = by;
    this.min = min;
    this.max = max;
  }

  public ZRangeParams(Keyword by, String min, String max) {
    this(by, from(min), from(max));
  }

  public ZRangeParams(Keyword by, byte[] min, byte[] max) {
    this(by, from(min), from(max));
  }

  public static ZRangeParams zrangeByLexParams(String min, String max) {
    return new ZRangeParams(BYLEX, min, max);
  }

View on GitHub (pinned to 6dac31d4c2)