apache/druid · error · IllegalArgumentException

Unknown format version for FrontCodedIndexed

Error message

Unknown format version for FrontCodedIndexed [%s], must be [%s] or [%s]

What it means

validateVersion rejects any FrontCodedIndexed format version byte other than V0 (0) or V1 (1). The version is read from the serialized header; if it does not match a supported version the reader cannot know the on-disk layout, so it throws IAE. This guards against reading segments written by newer/other engines.

Solutions

1. Upgrade all Druid nodes to a version that supports the segment's FrontCodedIndexed version (keep the cluster on one version during segment reads)
2. Re-ingest or re-index the affected segments with the older supported format if you must stay on the old version
3. Verify the buffer alignment/version byte — if the segment file is corrupted, restore from a backup and re-load the segment
4. Check historical/middle-manager version consistency so segments never cross incompatible versions

if (version != FrontCodedIndexed.V0 && version != FrontCodedIndexed.V1) {
  throw new IllegalArgumentException("Unsupported FrontCodedIndexed version: " + version);
}

try {
  FrontCodedIndexed.read(buffer, order, length, version);
} catch (IllegalArgumentException e) {
  // segment written by an incompatible/newer version; re-ingest or upgrade
}

When it happens

Trigger: Reading a FrontCodedIndexed whose header byte is not V0 or V1 — typically segments written by a newer Druid version (V2 and later) being read by an older runtime, or a corrupted/truncated buffer where the version byte is garbage.

Common situations: Rolling upgrade where older Druid nodes read segments written by newer ones; mixing Druid versions in a cluster; reading copied/edited segment files; deserialize bugs that misalign the buffer.

Related errors

• bucketSize must be a power of two but was[%,d]
• bucketSize must be a power of two but was[%,d]
• bucketSize must be a power of two (from 1 up to 128) but…
• cannot stringify array type
• Column capacity exceeded

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/data/FrontCodedIndexed.java:87

 * then a linear scan within the bucket to find the matching value (or negative insertion point -1 for values that
 * are not present).
 * <p>
 * The value iterator reads an entire bucket at a time, reconstructing the values into an array to iterate within the
 * bucket before moving onto the next bucket as the iterator is consumed.
 * <p>
 * This class is not thread-safe since during operation modifies positions of a shared buffer.
 */
public abstract class FrontCodedIndexed implements Indexed<ByteBuffer>
{
  public static final byte V0 = 0;
  public static final byte V1 = 1;
  public static final byte DEFAULT_VERSION = V1;
  public static final int DEFAULT_BUCKET_SIZE = 4;

  public static byte validateVersion(byte version)
  {
    if (version != FrontCodedIndexed.V0 && version != FrontCodedIndexed.V1) {
      throw new IAE(
          "Unknown format version for FrontCodedIndexed [%s], must be [%s] or [%s]",
          version,
          FrontCodedIndexed.V0,
          FrontCodedIndexed.V1
      );
    }
    return version;
  }

  public static Supplier<FrontCodedIndexed> read(ByteBuffer buffer, ByteOrder ordering)
  {
    final ByteBuffer orderedBuffer = buffer.asReadOnlyBuffer().order(ordering);
    final byte version = orderedBuffer.get();
    Preconditions.checkArgument(version == V0 || version == V1, "only V0 and V1 exist, encountered " + version);
    final int bucketSize = Byte.toUnsignedInt(orderedBuffer.get());
    final boolean hasNull = TypeStrategies.IS_NULL_BYTE == orderedBuffer.get();
    final int numValues = VByte.readInt(orderedBuffer);
    // size of offsets + values

View on GitHub (pinned to 9b90983fd2)