apache/druid · error · UOE

Unsupported string encoding [%s]

Error message

Unsupported string encoding [%s]

What it means

HllSketchBuildUtil.updateSketchWithString throws UnsupportedOperationException (UOE) when the configured StringEncoding is neither UTF8 nor UTF16LE. The HLL sketch update path only supports those two encodings for string values; any other enum value reaches the default branch.

Source

Thrown at extensions-core/datasketches/src/main/java/org/apache/druid/query/aggregation/datasketches/hll/HllSketchBuildUtil.java:99

  private static void updateSketchWithString(
      final HllSketch sketch,
      final StringEncoding stringEncoding,
      @Nullable final String value
  )
  {
    if (value == null) {
      return;
    }

    switch (stringEncoding) {
      case UTF8:
        sketch.update(StringUtils.toUtf8(value));
        break;
      case UTF16LE:
        sketch.update(value.toCharArray());
        break;
      default:
        throw new UOE("Unsupported string encoding [%s]", stringEncoding);
    }
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Set the aggregator's stringEncoding to exactly 'UTF8' or 'UTF16LE'.
  2. Remove the stringEncoding field entirely to use the default (UTF8).
  3. Validate query JSON against the Druid enum names for your Druid version.

Example fix

// before
{"type": "HLLSketchBuild", "name": "s", "fieldName": "v", "stringEncoding": "utf-8"}
// after
{"type": "HLLSketchBuild", "name": "s", "fieldName": "v", "stringEncoding": "UTF8"}
Defensive patterns

Strategy: validation

Validate before calling

if (stringEncoding != null && !stringEncoding.equals("UTF8") && !stringEncoding.equals("UTF16LE")) throw new IllegalArgumentException("stringEncoding must be UTF8 or UTF16LE");

Type guard

boolean validEncoding(StringEncoding e) { return e == StringEncoding.UTF8 || e == StringEncoding.UTF16LE; }

Try / catch

try { updateSketchWithString(sketch, enc, value); } catch (UOE e) { /* default to UTF8 and retry */ }

Prevention

When it happens

Trigger: An HLLSketchBuild aggregator spec carries a stringEncoding field with a value outside {UTF8, UTF16LE} — typically from a hand-edited native query JSON, a newer/older Druid version's enum name, or programmatic construction of the aggregator factory with a bad enum.

Common situations: Typos in JSON like 'utf-8' or 'utf8' if enum parsing allows other values; copying aggregator specs across Druid versions where the enum set changed; custom tooling generating aggregator specs with invalid encoding names.

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

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