apache/druid · error · ISE

Unknown encoding strategy

Error message

Unknown encoding strategy: %s

What it means

StringEncodingStrategies.getStringDictionaryWriter() selects the writer implementation based on the configured StringEncodingStrategy type (utf8, front-coded, etc.). This ISE is thrown when the strategy's getType() is not one of the known encoding types, so no dictionary writer can be constructed for segment output.

Solutions

  1. Use one of the supported encoding strategies (e.g. Utf8 or FrontCoded) in the column format spec
  2. Upgrade the Druid build so it recognizes the requested encoding strategy type
  3. If a custom strategy was added, register a writer branch for its type in StringEncodingStrategies

Example fix

// before
"stringDictionaryEncoding": { "type": "frontcoded-x" } // unknown type
// after
"stringDictionaryEncoding": { "type": "front-coded", "bucketSize": 16 } // supported strategy
Defensive patterns

Strategy: validation

Validate before calling

if (!EnumSet.of(StringEncodingStrategy.Utf8.TYPE, StringEncodingStrategy.FrontCoded.TYPE).contains(encodingStrategy.getType())) {
  throw new IllegalArgumentException("Unsupported encoding strategy: " + encodingStrategy.getType());
}

Type guard

boolean hasWriter(StringEncodingStrategy s) {
  return "utf8".equals(s.getType()) || "front-coded".equals(s.getType());
}

Try / catch

try {
  writer = StringEncodingStrategies.getStringDictionaryWriter(strategy, buffer, writeoutMedium);
} catch (ISE e) {
  LOG.warn(e, "Unknown encoding strategy [%s], falling back to utf8", strategy.getType());
  writer = StringEncodingStrategies.getStringDictionaryWriter(new StringEncodingStrategy.Utf8(), buffer, writeoutMedium);
}

Prevention

When it happens

Trigger: Calling getStringDictionaryWriter() with a StringEncodingStrategy whose getType() is an unknown/unregistered constant — typically a custom or future encoding strategy type supplied via column format configuration while writing a string dictionary.

Common situations: Typo or invalid value in a custom column format/encoding strategy configuration; running a segment-writing build older than the strategy type being requested (version skew); a custom extension returning an unrecognized strategy type.

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/fe60f1853bc67a9b. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/column/StringEncodingStrategies.java:68

    // write plain utf8 in the legacy format, where generic indexed was written directly
    if (StringEncodingStrategy.UTF8.equals(encodingStrategy.getType())) {
      return new GenericIndexedWriter<>(writeoutMedium, fileName, GenericIndexed.STRING_STRATEGY);
    } else {
      // otherwise, we wrap in an EncodedStringDictionaryWriter so that we write a small header that includes
      // a version byte that should hopefully never conflict with a GenericIndexed version, along with a byte
      // from StringEncodingStrategy.getId to indicate which encoding strategy is used for the dictionary before
      // writing the dictionary itself
      DictionaryWriter<byte[]> writer;
      if (StringEncodingStrategy.FRONT_CODED.equals(encodingStrategy.getType())) {
        StringEncodingStrategy.FrontCoded strategy = (StringEncodingStrategy.FrontCoded) encodingStrategy;
        writer = new FrontCodedIndexedWriter(
            writeoutMedium,
            IndexIO.BYTE_ORDER,
            strategy.getBucketSize(),
            strategy.getFormatVersion()
        );
      } else {
        throw new ISE("Unknown encoding strategy: %s", encodingStrategy.getType());
      }
      return new EncodedStringDictionaryWriter(writer, encodingStrategy);
    }
  }

  public static Supplier<? extends Indexed<ByteBuffer>> getStringDictionarySupplier(
      SegmentFileMapper mapper,
      ByteBuffer stringDictionaryBuffer,
      ByteOrder byteOrder
  )
  {
    final int dictionaryStartPosition = stringDictionaryBuffer.position();
    final byte dictionaryVersion = stringDictionaryBuffer.get();

    if (dictionaryVersion == EncodedStringDictionaryWriter.VERSION) {
      final byte encodingId = stringDictionaryBuffer.get();
      if (encodingId == StringEncodingStrategy.FRONT_CODED_ID) {
        return FrontCodedIndexed.read(

View on GitHub (pinned to 9b90983fd2)