apache/druid · error · ISE

impossible, unknown encoding strategy id

Error message

impossible, unknown encoding strategy id: %s

What it means

StringEncodingStrategies.getStringDictionarySupplier() reads a persisted string dictionary and dispatches on the stored encoding id (legacy, UTF8_ID, front-coded ids). This ISE is thrown when the byte-encoded encoding id read from the segment is not recognized — the dictionary on disk was written with an encoding this reader cannot decode.

Solutions

  1. Upgrade the reading Druid cluster to at least the version that wrote the segments
  2. Restore affected segments from a backup or re-ingest the data with the current version
  3. Verify segment file integrity (corruption can produce a bogus encoding id)

Example fix

// before
// old cluster (e.g. 0.22) reading a segment written by 2023.x with a new front-coded encoding id
// after
// upgrade the old cluster so its reader recognizes the id:
// <druid.version>2023.x</druid.version> in pom, or redeploy matching distribution
Defensive patterns

Strategy: try-catch

Try / catch

try {
  Supplier<? extends Indexed<ByteBuffer>> dict = StringEncodingStrategies.getStringDictionarySupplier(buffer, mapper);
} catch (ISE e) {
  throw new SegmentLoadingException(e, "Segment dictionary uses an unknown encoding id — upgrade the reader or re-ingest");
}

Prevention

When it happens

Trigger: Reading a segment whose serialized dictionary header contains an encodingId unknown to this build, e.g. a segment written by a newer Druid version using an encoding id introduced after this reader, or a corrupted dictionary buffer yielding a bogus id.

Common situations: Version skew: newer writers produce segments that older readers cannot load; manually copied/mixed segment files across clusters; corrupted segment files on deep storage.

Related errors

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

Appendix: source

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

  )
  {
    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(
            stringDictionaryBuffer,
            byteOrder
        );
      } else if (encodingId == StringEncodingStrategy.UTF8_ID) {
        // this cannot happen naturally right now since generic indexed is written in the 'legacy' format, but
        // this provides backwards compatibility should we switch at some point in the future to always
        // writing dictionaryVersion
        return GenericIndexed.read(stringDictionaryBuffer, GenericIndexed.UTF8_STRATEGY, mapper)::singleThreaded;
      } else {
        throw new ISE("impossible, unknown encoding strategy id: %s", encodingId);
      }
    } else {
      // legacy format that only supports plain utf8 enoding stored in GenericIndexed and the byte we are reading
      // as dictionaryVersion is actually also the GenericIndexed version, so we reset start position so the
      // GenericIndexed version can be correctly read
      stringDictionaryBuffer.position(dictionaryStartPosition);
      return GenericIndexed.read(stringDictionaryBuffer, GenericIndexed.UTF8_STRATEGY, mapper)::singleThreaded;
    }
  }

  /**
   * Adapter to convert {@link Indexed<ByteBuffer>} with utf8 encoded bytes into {@link Indexed<String>} to be friendly
   * to consumers.
   */
  public static final class Utf8ToStringIndexed implements Indexed<String>
  {
    private final Indexed<ByteBuffer> delegate;

View on GitHub (pinned to 9b90983fd2)