redis/jedis · error · IllegalArgumentException

Either BYRADIUS or BYBOX must be used.

Error message

Either BYRADIUS or BYBOX must be used.

What it means

GEOSEARCH requires a search area definition; without BYRADIUS or BYBOX the command is invalid. GeoSearchParam.addParams() verifies that exactly one shape was configured and throws this IllegalArgumentException when neither is set.

Solutions

1. Add .byRadius(radius, unit) or .byBox(width, height, unit) to the GeoSearchParam
2. Validate the radius/box inputs before building params so the shape call is always reached
3. Rebuild the param chain ensuring origin + shape are both present

Example fix

// before
GeoSearchParam p = new GeoSearchParam().fromMember("sicily").withCoord();
// after
GeoSearchParam p = new GeoSearchParam().fromMember("sicily").byRadius(100, GeoUnit.KM).withCoord();

if (radius == null && (boxW == null || boxH == null)) throw new IllegalStateException("GEOSEARCH needs byRadius or byBox");

try {
  jedis.geosearch(key, params);
} catch (IllegalArgumentException e) {
  log.error("GEOSEARCH shape missing", e);
}

When it happens

Trigger: Executing GEOSEARCH/GEOSEARCHSTORE with a GeoSearchParam that has only an origin and/or options (e.g. new GeoSearchParam().fromMember("sicily").withCoord()) but no byRadius(...) or byBox(...) call.

Common situations: Forgetting the shape when constructing params incrementally; conditional shape code where the condition never fired; incomplete migration from GEORADIUS where the radius became a separate param call that was dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Either FROMMEMBER or FROMLONLAT must be used.
• COUNT must be set before ANY to be set
• Both FROMMEMBER and FROMLONLAT cannot be used.
• Both BYRADIUS and BYBOX cannot be used.
• COUNT or EXACTLY must be specified.

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/params/GeoSearchParam.java:135

  public void addParams(CommandArguments args) {
    if (fromMember && fromLonLat) {
      throw new IllegalArgumentException("Both FROMMEMBER and FROMLONLAT cannot be used.");
    } else if (fromMember) {
      args.add(Keyword.FROMMEMBER).add(member);
    } else if (fromLonLat) {
      args.add(Keyword.FROMLONLAT).add(coord.getLongitude()).add(coord.getLatitude());
    } else {
      throw new IllegalArgumentException("Either FROMMEMBER or FROMLONLAT must be used.");
    }

    if (byRadius && byBox) {
      throw new IllegalArgumentException("Both BYRADIUS and BYBOX cannot be used.");
    } else if (byRadius) {
      args.add(Keyword.BYRADIUS).add(radius).add(unit);
    } else if (byBox) {
      args.add(Keyword.BYBOX).add(width).add(height).add(unit);
    } else {
      throw new IllegalArgumentException("Either BYRADIUS or BYBOX must be used.");
    }

    if (withCoord) {
      args.add(Keyword.WITHCOORD);
    }
    if (withDist) {
      args.add(Keyword.WITHDIST);
    }
    if (withHash) {
      args.add(Keyword.WITHHASH);
    }

    if (count != null) {
      args.add(Keyword.COUNT).add(count);
      if (any) {
        args.add(Keyword.ANY);
      }
    }

View on GitHub (pinned to 6dac31d4c2)