redis/jedis · error · IllegalArgumentException

EXCLUDEEMPTY is not allowed with GROUPBY.

Error message

EXCLUDEEMPTY is not allowed with GROUPBY.

What it means

TSMRangeParams.addParams rejects combining EXCLUDEEMPTY with GROUPBY: when excludeEmpty is true and both groupByLabel and groupByReduce are set, it throws IllegalArgumentException("EXCLUDEEMPTY is not allowed with GROUPBY."). RedisTimeSeries does not permit this flag combination in TS.MRANGE, so the client blocks it before sending the command.

Solutions

1. Remove excludeEmpty() when grouping; pre-filter empty series or post-process results to drop empty buckets instead.
2. Keep EXCLUDEEMPTY only for plain (non-GROUPBY) filtered queries.
3. Add mutual-exclusion validation in your config/UI so both options cannot be enabled simultaneously.

Example fix

// before
params.excludeEmpty().groupBy("region", Reduce.SUM); // throws
// after
params.groupBy("region", Reduce.SUM); // drop EXCLUDEEMPTY when using GROUPBY

if (useExcludeEmpty && groupByLabel != null) {
  throw new IllegalArgumentException("EXCLUDEEMPTY cannot be combined with GROUPBY");
}

boolean isCompatible(TSMRangeParams p, boolean excludeEmpty, String groupByLabel, Reduce reduce) {
  return !(excludeEmpty && groupByLabel != null && reduce != null);
}

try {
  jedis.ts.mrange(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("EXCLUDEEMPTY")) {
    log.warn("Dropping EXCLUDEEMPTY because GROUPBY is set");
  } else throw e;
}

When it happens

Trigger: Calling both excludeEmpty()/setExcludeEmpty(true) and groupBy(label, reduce) (e.g. groupBy("region", Reduce.SUM)) on the same TSMRangeParams instance and then executing the query.

Common situations: Cumulative builder code where a base params object gets excludeEmpty from one config option and GROUPBY from another, both enabled; copy-pasting example queries that each use one of the features; flags toggled by different user preferences.

Related errors

• Aggregators must be non-null and non-empty
• Aggregators must not contain null elements
• FILTER arguments must be set.
• Aggregators must be non-null and non-empty
• Aggregators must not contain null elements

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/timeseries/TSMRangeParams.java:251

    this.filters = filters;
    return this;
  }

  public TSMRangeParams groupBy(String label, String reduce) {
    this.groupByLabel = label;
    this.groupByReduce = reduce;
    return this;
  }

  @Override
  public void addParams(CommandArguments args) {

    if (filters == null) {
      throw new IllegalArgumentException("FILTER arguments must be set.");
    }

    if (excludeEmpty && groupByLabel != null && groupByReduce != null) {
      throw new IllegalArgumentException("EXCLUDEEMPTY is not allowed with GROUPBY.");
    }

    if (fromTimestamp == null) {
      args.add(MINUS);
    } else {
      args.add(toByteArray(fromTimestamp));
    }

    if (toTimestamp == null) {
      args.add(PLUS);
    } else {
      args.add(toByteArray(toTimestamp));
    }

    if (latest) {
      args.add(LATEST);
    }

View on GitHub (pinned to 6dac31d4c2)