What causes "Escape must be null or a single character" in apache/druid?

Change the escape value to a single character, or remove it (null) entirely.

apache/druid · error · IllegalArgumentException

Escape must be null or a single character

Error message

Escape must be null or a single character

What it means

LikeDimFilter validates that its escape argument is either null (no escaping) or exactly one character, since escapes operate per character in LIKE-style pattern matching. Any longer string is rejected at construction with IllegalArgumentException.

Source

Thrown at processing/src/main/java/org/apache/druid/query/filter/LikeDimFilter.java:78

  private final FilterTuning filterTuning;
  private final LikeMatcher likeMatcher;

  @JsonCreator
  public LikeDimFilter(
      @JsonProperty("dimension") final String dimension,
      @JsonProperty("pattern") final String pattern,
      @JsonProperty("escape") @Nullable final String escape,
      @JsonProperty("extractionFn") @Nullable final ExtractionFn extractionFn,
      @JsonProperty("filterTuning") @Nullable final FilterTuning filterTuning
  )
  {
    this.dimension = Preconditions.checkNotNull(dimension, "dimension");
    this.pattern = Preconditions.checkNotNull(pattern, "pattern");
    this.extractionFn = extractionFn;
    this.filterTuning = filterTuning;

    if (escape != null && escape.length() != 1) {
      throw new IllegalArgumentException("Escape must be null or a single character");
    } else {
      this.escapeChar = escape == null ? null : escape.charAt(0);
    }

    this.likeMatcher = LikeMatcher.from(pattern, this.escapeChar);
  }

  @VisibleForTesting
  public LikeDimFilter(
      final String dimension,
      final String pattern,
      @Nullable final String escape,
      @Nullable final ExtractionFn extractionFn
  )
  {
    this(dimension, pattern, escape, extractionFn, null);
  }

View on GitHub (pinned to 9b90983fd2)

Solutions

Change the escape value to a single character, or remove it (null) entirely.
If a multi-character escape sequence is needed, pre-process the pattern manually with LikeMatcher semantics instead of using escape.
Validate user-supplied escape input in your API layer before building the filter.

Example fix

// before
new LikeDimFilter("dim", "foo\\%bar", "\\%", null);
// after
new LikeDimFilter("dim", "foo\\%bar", "\\", null); // single-char escape

Defensive patterns

Strategy: validation

Validate before calling

if (escape != null && escape.length() != 1) { throw new IllegalArgumentException("escape must be null or a single character"); }

Type guard

boolean validEscape = escape == null || escape.length() == 1;

Try / catch

try { new LikeDimFilter(dim, pattern, escape, tuning); } catch (IllegalArgumentException e) { /* sanitize escape and retry */ }

Prevention

Validate user-supplied escape strings in your API layer
Use null escape unless per-character escaping is truly needed
Remember escape is one char, not an escape prefix string

When it happens

Trigger: Constructing new LikeDimFilter(...) or deserializing a JSON like filter where "escape" is a multi-character string, e.g. "escape": "\\\\".

Common situations: Users writing JSON filters who mistake escape for an escape string/prefix (like SQL ESCAPE clauses with multiple chars) or who paste two characters by accident.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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