provectus/kafka-ui · error · IllegalArgumentException

Unrecognized version

Error message

Unrecognized version: ${version}

What it means

ConsumerOffsetsSerde's valueDeserializer parses the version short at the start of __consumer_offsets value records and dispatches to schema readers for versions 0-4. An unrecognized version has no matching metadata schema branch, so IllegalArgumentException is thrown before falling back to a plain JSON render. The catch block then retries deserialization treating the payload generically.

Solutions

1. Upgrade kafka-ui so its metadata schemas cover your broker's __consumer_offsets version
2. Ensure the serde is bound only to __consumer_offsets
3. Inspect the record; if it is truly v5+, extend the switch with a new metadataSchema

short v = ByteBuffer.wrap(data).getShort(); if (v > 4) { /* unsupported metadata version */ }

boolean supportedValueVersion(byte[] d) { return d != null && d.length >= 2 && ByteBuffer.wrap(d).getShort() <= 4; }

try { result = serde.deserialize(...); } catch (IllegalArgumentException e) { log.warn("unsupported value version: {}", e.getMessage()); }

When it happens

Trigger: valueDeserializer receives a value whose version short is >4 for the offset-metadata branch of the switch (after the first short is read).

Common situations: Newer Kafka brokers writing __consumer_offsets metadata values with a version kafka-ui predates; decoding a wrong topic's records with this serde; malformed messages whose second short is misread as a version.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown group metadata message version
• Message buffer is not read to the end, which is likely…
• Serde can't be applied for ' ' topic's serialization
• Serde ' ' can't be applied to ' ' topic
• Application config isn't valid. Cluster names should be…

AI-assisted analysis of provectus/kafka-ui@83b5a60cc0 (2026-09-08). Data as JSON: /api/errors/949455aa14b10dd8. Report an issue: GitHub.

Appendix: source

Thrown at kafka-ui-api/src/main/java/com/provectus/kafka/ui/serdes/builtin/ConsumerOffsetsSerde.java:278

            Field.TaggedFieldsSection.of()
        );

    return (headers, data) -> {
      String result;
      var bb = ByteBuffer.wrap(data);
      short version = bb.getShort();
      // ideally, we should distinguish if value is commit or metadata
      // by checking record's key, but our current serde structure doesn't allow that.
      // so, we are trying to parse into metadata first and after into commit msg
      try {
        result = toJson(
            switch (version) {
              case 0 -> metadataSchema0.read(bb);
              case 1 -> metadataSchema1.read(bb);
              case 2 -> metadataSchema2.read(bb);
              case 3 -> metadataSchema3.read(bb);
              case 4 -> metadataSchema4.read(bb);
              default -> throw new IllegalArgumentException("Unrecognized version: " + version);
            }
        );
      } catch (Throwable e) {
        bb = bb.rewind();
        bb.getShort(); // skipping version
        result = toJson(
            switch (version) {
              case 0 -> commitOffsetSchemaV0.read(bb);
              case 1 -> commitOffsetSchemaV1.read(bb);
              case 2 -> commitOffsetSchemaV2.read(bb);
              case 3 -> commitOffsetSchemaV3.read(bb);
              case 4 -> commitOffsetSchemaV4.read(bb);
              default -> throw new IllegalArgumentException("Unrecognized version: " + version);
            }
        );
      }

      if (bb.remaining() != 0) {

View on GitHub (pinned to 83b5a60cc0)