apache/druid · error · IllegalArgumentException

Unknown version[ ]

Error message

Unknown version[%s]

What it means

VSizeColumnarInts.readFromByteBuffer reads a version byte and deserializes accordingly; a version byte matching no known version throws this IAE. It means the buffer is not a valid serialized VSizeColumnarInts — corrupted, misaligned, or written by an incompatible format/version.

Solutions

1. Ensure segments are written by a compatible Druid version; re-ingest or upgrade if needed
2. Verify the buffer position points at the column's start (version byte), not into its body
3. Check file integrity and re-fetch the segment from deep storage
4. For custom writers, serialize with VSizeColumnarInts.writeTo/its serializer so the version header is present

Example fix

// before
ByteBuffer col = wholeBuffer.slice(); col.position(start + 1); // skipped version byte
VSizeColumnarInts ints = VSizeColumnarInts.readFromByteBuffer(col);
// after
ByteBuffer col = wholeBuffer.slice(); col.position(start);
VSizeColumnarInts ints = VSizeColumnarInts.readFromByteBuffer(col);

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

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

try { col = VSizeColumnarInts.readFromByteBuffer(buffer); } catch (IAE e) { if (e.getMessage().startsWith("Unknown version")) { /* reload/repair segment */ } else throw e; }

When it happens

Trigger: Calling VSizeColumnarInts.readFromByteBuffer on a buffer whose leading byte is not a supported version marker — reading a foreign column format, or a buffer positioned mid-payload.

Common situations: Segment files produced by a different Druid version, custom serialization code writing raw ints without a version header, or offsets pointing at the wrong column boundary.

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/3d93f4712e1f340c. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/data/VSizeColumnarInts.java:213

  public static VSizeColumnarInts 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 VSizeColumnarInts(
          bufferToUse,
          numBytes
      );
    }

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

  @Override
  public void close()
  {
    // Do nothing
  }

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

View on GitHub (pinned to 9b90983fd2)