apache/druid · critical · IllegalArgumentException

Unsupported multi-value version[%s]

Error message

Unsupported multi-value version[%s]

What it means

readMultiValuedColumn handles three known VERSION values (UNCOMPRESSED_SINGLE_VALUE-family, UNCOMPRESSED_WITH_FLAGS, COMPRESSED). A multi-valued column stored with any other VERSION enum value triggers this IAE in the default branch. This is a format-compatibility failure: the segment was written by an unknown/incompatible writer.

Source

Thrown at processing/src/main/java/org/apache/druid/segment/serde/DictionaryEncodedColumnPartSerde.java:464

          }
          case UNCOMPRESSED_WITH_FLAGS: {
            if (Feature.MULTI_VALUE.isSet(flags)) {
              return VSizeColumnarMultiInts.readFromByteBuffer(buffer);
            } else {
              throw new IAE("Unrecognized multi-value flag[%d] for version[%s]", flags, version);
            }
          }
          case COMPRESSED: {
            if (Feature.MULTI_VALUE.isSet(flags)) {
              return CompressedVSizeColumnarMultiIntsSupplier.fromByteBuffer(buffer, byteOrder, fileMapper);
            } else if (Feature.MULTI_VALUE_V3.isSet(flags)) {
              return V3CompressedVSizeColumnarMultiIntsSupplier.fromByteBuffer(buffer, byteOrder, fileMapper);
            } else {
              throw new IAE("Unrecognized multi-value flag[%d] for version[%s]", flags, version);
            }
          }
          default:
            throw new IAE("Unsupported multi-value version[%s]", version);
        }
      }
    };
  }

  private static boolean mustWriteFlags(final int flags)
  {
    // Flags that are not implied by version codes < COMPRESSED must be written. This includes MULTI_VALUE_V3.
    return flags != NO_FLAGS && flags != Feature.MULTI_VALUE.getMask();
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Upgrade the Druid nodes loading the segment to the version that wrote it.
  2. Re-ingest the affected data so segments are written in a format the current cluster supports.
  3. Restore corrupt segments from deep storage.
  4. Standardize one Druid version across the cluster before sharing segment storage.
Defensive patterns

Strategy: validation

Try / catch

try {
    return adapter.getColumn("multiDim");
} catch (IAE e) {
    if (e.getMessage().contains("Unsupported multi-value version")) {
        throw new IllegalStateException("Segment written by incompatible Druid version; upgrade required", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Deserializing a multi-valued dictionary-encoded string column whose VERSION enum value falls outside the switch's known cases during segment load.

Common situations: Downgraded Druid reading newer-format segments; segment corruption flipping the version enum ordinal; hand-edited or converted segment metadata.

Related errors

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