apache/druid · error · IllegalArgumentException

Unknown version[ ]

Error message

Unknown version[%s]

What it means

VSizeColumnarMultiInts.readFromByteBuffer dispatches on a leading version byte and throws IAE 'Unknown version' when it matches nothing. The buffer is not a valid serialized VSizeColumnarMultiInts — wrong format, corruption, or misaligned position.

Solutions

1. Confirm writer/reader Druid versions are compatible; re-ingest or upgrade
2. Point the buffer at the exact column start offset where the version byte lives
3. Validate segment checksums and re-download corrupted files
4. Serialize via the class's own writer so version metadata is emitted

Example fix

// before
buf.position(offset + HEADER_SKIP); // lands past the version byte
VSizeColumnarMultiInts col = VSizeColumnarMultiInts.readFromByteBuffer(buf);
// after
buf.position(offset);
VSizeColumnarMultiInts col = VSizeColumnarMultiInts.readFromByteBuffer(buf);

if (buffer.remaining() < 1) throw new IllegalStateException("buffer too short");
byte version = buffer.get(buffer.position());
if (version != VSizeColumnarMultiInts.VERSION) throw new IllegalStateException("unsupported version " + version);

boolean isSupportedVersion(ByteBuffer buf) { return buf.remaining() >= 1 && buf.get(buf.position()) == VSizeColumnarMultiInts.VERSION; }

try { col = VSizeColumnarMultiInts.readFromByteBuffer(buffer); } catch (IAE e) { if (e.getMessage().startsWith("Unknown version")) { /* mark segment bad, re-ingest */ } else throw e; }

When it happens

Trigger: Deserializing a buffer whose first byte is not a supported version — reading a column written by a different format, or positioning the buffer inside the payload instead of at its start.

Common situations: Version-skew between writer and reader Druid versions, segment corruption on deep storage, custom tooling writing/reading columns manually.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Unknown version[ ]
• Unknown version[ ]
• Object cannot be deserialized to a Moments Sketch:
• bucketSize must be a power of two but was[%,d]
• bucketSize must be a power of two but was[%,d]

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/data/VSizeColumnarMultiInts.java:186

  {
    return this;
  }

  public static VSizeColumnarMultiInts readFromByteBuffer(ByteBuffer buffer)
  {
    byte versionFromBuffer = buffer.get();

    if (VERSION == versionFromBuffer) {
      int numBytes = buffer.get();
      int size = buffer.getInt();
      ByteBuffer bufferToUse = buffer.asReadOnlyBuffer();
      bufferToUse.limit(bufferToUse.position() + size);
      buffer.position(bufferToUse.limit());

      return new VSizeColumnarMultiInts(bufferToUse, numBytes);
    }

    throw new IAE("Unknown version[%s]", versionFromBuffer);
  }

  @Override
  public Iterator<IndexedInts> iterator()
  {
    return IndexedIterable.create(this).iterator();
  }

  @Override
  public void close()
  {
    // no-op
  }

  @Override
  public void inspectRuntimeShape(RuntimeShapeInspector inspector)
  {
    inspector.visit("theBuffer", theBuffer);

View on GitHub (pinned to 9b90983fd2)