redis/jedis · error · IllegalArgumentException

Must choose exactly one filter in

Error message

Must choose exactly one filter in ${className}

What it means

COMMAND LIST FILTERBY accepts exactly one filter (MODULE, ACLCAT, or PATTERN). CommandListFilterByParams.addParams validates that precisely one of moduleName, category, or pattern was set; if none or more than one is set, it throws IllegalArgumentException naming the concrete class via getClass().getSimpleName().

Solutions

1. Set exactly one of module(), aclCat(), or pattern() before passing the params object to COMMAND LIST FILTERBY.
2. If multiple filters come from user input, validate/whitelist to a single filter before building the params.
3. Issue separate COMMAND LIST FILTERBY calls (one per filter) and merge the results in application code if multiple criteria are needed.

Example fix

// before
CommandListFilterByParams params = CommandListFilterByParams.CommandListFilterByParamsBuilder
    .module("search").pattern("foo*").build(); // two filters -> error
// after
CommandListFilterByParams params = CommandListFilterByParams.CommandListFilterByParamsBuilder
    .pattern("foo*").build(); // exactly one filter

int set = (moduleName != null ? 1 : 0) + (category != null ? 1 : 0) + (pattern != null ? 1 : 0);
if (set != 1) throw new IllegalArgumentException("choose exactly one of module/aclCat/pattern");

try {
  jedis.commandListFilterBy(params);
} catch (IllegalArgumentException e) {
  log.error("FILTERBY params invalid: {}", e.getMessage());
}

When it happens

Trigger: Calling CommandListFilterByParams with: no filter at all; both MODULE and ACLCAT; both MODULE and PATTERN; both ACLCAT and PATTERN; or all three set.

Common situations: Composing filters from user input where several optional filter fields are populated; copying a params builder and adding a second filter; generic param-passing code that sets defaults for multiple filter fields.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• FAILOVER with force option requires both a timeout and…
• Cluster mode only supports SCAN command with MATCH pattern…
• HashImport ' ' expects values but got
• Cache cannot be null!
• Version can not be null

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/params/CommandListFilterByParams.java:47

    this.pattern = pattern;
    return this;
  }

  @Override
  public void addParams(CommandArguments args) {
    args.add(Keyword.FILTERBY);

    if (moduleName != null && category == null && pattern == null) {
      args.add(Keyword.MODULE);
      args.add(moduleName);
    } else if (moduleName == null && category != null && pattern == null) {
      args.add(Keyword.ACLCAT);
      args.add(category);
    } else if (moduleName == null && category == null && pattern != null) {
      args.add(Keyword.PATTERN);
      args.add(pattern);
    } else {
      throw new IllegalArgumentException("Must choose exactly one filter in "
          + getClass().getSimpleName());
    }
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;
    CommandListFilterByParams that = (CommandListFilterByParams) o;
    return Objects.equals(moduleName, that.moduleName) && Objects.equals(category, that.category) && Objects.equals(pattern, that.pattern);
  }

  @Override
  public int hashCode() {
    return Objects.hash(moduleName, category, pattern);
  }
}

View on GitHub (pinned to 6dac31d4c2)