apache/druid · error · IllegalArgumentException

Unknown string comparator

Error message

Unknown string comparator[%s]

What it means

StringComparator.fromString maps comparator names (lexicographic, alphanumeric, numeric, version, natural) to comparator instances. An unknown name is rejected with an IAE. This validates the comparator string supplied in query JSON (e.g. on DimFilter, extractor sort orders).

Solutions

1. Use one of the valid names: lexicographic, alphanumeric, numeric, version, natural
2. Check server version — newer comparators on an older broker will fail
3. Correct the query JSON field name and value

Example fix

// before
"sortOrder": {"type": "lexographic"}
// after
"sortOrder": {"type": "lexicographic"}

final Set<String> VALID = Set.of("lexicographic","alphanumeric","numeric","version","natural");
if (comparator != null && !VALID.contains(comparator)) {
  throw new IllegalArgumentException("unknown comparator: " + comparator);
}

try {
  submitQuery(queryJson);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown string comparator")) {
    submitQuery(fixComparator(queryJson));
  } else throw e;
}

When it happens

Trigger: Query JSON contains "comparator": "<typo>" or a comparator name unsupported by the running Druid version, passed to StringComparator.fromString.

Common situations: Hand-written JSON with a misspelled comparator (e.g. "lexographic"); client SDK serializing a comparator string not supported by the server version; using the enum name instead of its string form.

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

• Order required for column
• Adjacent intervals are not sorted
• Cannot add merged batches for level
• Cannot create comparator for array type
• Cannot set mergers for final level more than once

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/8e605ade17f136a4. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/query/ordering/StringComparator.java:47

{
  @JsonCreator
  public static StringComparator fromString(String type)
  {
    switch (StringUtils.toLowerCase(type)) {
      case StringComparators.LEXICOGRAPHIC_NAME:
        return StringComparators.LEXICOGRAPHIC;
      case StringComparators.ALPHANUMERIC_NAME:
        return StringComparators.ALPHANUMERIC;
      case StringComparators.STRLEN_NAME:
        return StringComparators.STRLEN;
      case StringComparators.NUMERIC_NAME:
        return StringComparators.NUMERIC;
      case StringComparators.VERSION_NAME:
        return StringComparators.VERSION;
      case StringComparators.NATURAL_NAME:
        return StringComparators.NATURAL;
      default:
        throw new IAE("Unknown string comparator[%s]", type);
    }
  }

  public abstract byte[] getCacheKey();
}

View on GitHub (pinned to 9b90983fd2)