apache/druid · error · IllegalArgumentException

Unrecognized multi-value flag[%d] for version[%s]

Error message

Unrecognized multi-value flag[%d] for version[%s]

What it means

For UNCOMPRESSED_WITH_FLAGS single-format multi-value columns, the stored flags int must have the MULTI_VALUE feature bit set; anything else is not a readable layout, so readMultiValuedColumn throws this IAE with the raw flags value and version. It indicates a corrupt or hand-modified column header.

Source

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

        }
      }

      private WritableSupplier<ColumnarMultiInts> readMultiValuedColumn(
          VERSION version,
          ByteBuffer buffer,
          int flags,
          SegmentFileMapper fileMapper
      )
      {
        switch (version) {
          case UNCOMPRESSED_MULTI_VALUE: {
            return VSizeColumnarMultiInts.readFromByteBuffer(buffer);
          }
          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);
        }
      }
    };
  }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Restore the segment from deep storage or a backup; the flags field is corrupt.
2. Re-ingest the affected time chunk to regenerate the segment.
3. Check for any custom tooling that rewrites or truncates segment files and stop using it on production segments.
4. If it reproduces from a task, capture the task logs and report the ingestion bug with Druid version details.

try {
    column = cache.getColumn("multiDim");
} catch (IAE e) {
    if (e.getMessage().contains("Unrecognized multi-value flag")) {
        log.warn("Corrupt flags in segment column; scheduling re-ingestion of %s", segmentId);
        reingestionService.submit(segmentId);
        return null;
    }
    throw e;
}

When it happens

Trigger: Reading a VERSION.UNCOMPRESSED_WITH_FLAGS multi-valued string column where Feature.MULTI_VALUE.isSet(flags) is false — i.e. the flags int in the serialized column is invalid for this read path.

Common situations: Segment file corruption (flags bytes overwritten or truncated file read from wrong offset); manually patched/converted segment files; bugs in custom code writing segments directly with the segment-writing APIs.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• Failed to deserialize V%s column.
• Unknown version[%s]
• Failed to deserialize V%s column.
• Failed to deserialize V%s column.
• Failed to deserialize V%s column.

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