{"record":{"id":"e65e7ba8a7645eed","repo":"apache/druid","slug":"unknown-format-version-for-frontcodedindexed-s","errorCode":null,"errorMessage":"Unknown format version for FrontCodedIndexed [%s], must be [%s] or [%s]","messagePattern":"Unknown format version for FrontCodedIndexed \\[(.+?)\\], must be \\[(.+?)\\] or \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/segment/data/FrontCodedIndexed.java","lineNumber":87,"sourceCode":" * then a linear scan within the bucket to find the matching value (or negative insertion point -1 for values that\n * are not present).\n * <p>\n * The value iterator reads an entire bucket at a time, reconstructing the values into an array to iterate within the\n * bucket before moving onto the next bucket as the iterator is consumed.\n * <p>\n * This class is not thread-safe since during operation modifies positions of a shared buffer.\n */\npublic abstract class FrontCodedIndexed implements Indexed<ByteBuffer>\n{\n  public static final byte V0 = 0;\n  public static final byte V1 = 1;\n  public static final byte DEFAULT_VERSION = V1;\n  public static final int DEFAULT_BUCKET_SIZE = 4;\n\n  public static byte validateVersion(byte version)\n  {\n    if (version != FrontCodedIndexed.V0 && version != FrontCodedIndexed.V1) {\n      throw new IAE(\n          \"Unknown format version for FrontCodedIndexed [%s], must be [%s] or [%s]\",\n          version,\n          FrontCodedIndexed.V0,\n          FrontCodedIndexed.V1\n      );\n    }\n    return version;\n  }\n\n  public static Supplier<FrontCodedIndexed> read(ByteBuffer buffer, ByteOrder ordering)\n  {\n    final ByteBuffer orderedBuffer = buffer.asReadOnlyBuffer().order(ordering);\n    final byte version = orderedBuffer.get();\n    Preconditions.checkArgument(version == V0 || version == V1, \"only V0 and V1 exist, encountered \" + version);\n    final int bucketSize = Byte.toUnsignedInt(orderedBuffer.get());\n    final boolean hasNull = TypeStrategies.IS_NULL_BYTE == orderedBuffer.get();\n    final int numValues = VByte.readInt(orderedBuffer);\n    // size of offsets + values","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/segment/data/FrontCodedIndexed.java#L69-L105","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade all Druid nodes to a version that supports the segment's FrontCodedIndexed version (keep the cluster on one version during segment reads)","Re-ingest or re-index the affected segments with the older supported format if you must stay on the old version","Verify the buffer alignment/version byte — if the segment file is corrupted, restore from a backup and re-load the segment","Check historical/middle-manager version consistency so segments never cross incompatible versions"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (version != FrontCodedIndexed.V0 && version != FrontCodedIndexed.V1) {\n  throw new IllegalArgumentException(\"Unsupported FrontCodedIndexed version: \" + version);\n}","typeGuard":null,"tryCatchPattern":"try {\n  FrontCodedIndexed.read(buffer, order, length, version);\n} catch (IllegalArgumentException e) {\n  // segment written by an incompatible/newer version; re-ingest or upgrade\n}","preventionTips":["Keep all Druid nodes on the same version, especially during rolling upgrades","Call FrontCodedIndexed.validateVersion before opening readers from raw buffers","Back up segments so corrupt or incompatible ones can be re-ingested","Never hand-edit or partially copy segment files"],"tags":["version","serialization","format"],"backgroundTag":"unsupported-enum-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}