provectus/kafka-ui · error · IllegalStateException

Unknown group metadata message version

Error message

Unknown group metadata message version: ${version}

What it means

ConsumerOffsetsSerde decodes Kafka's internal __consumer_offsets records. Keys are versioned binary records; when the leading version short is neither 0, 1 (offset commit keys) nor 2 (group metadata keys), the switch has no branch and IllegalStateException is thrown. This means the record is not a recognized __consumer_offsets key format for this serde.

Solutions

1. Apply the serde only to the __consumer_offsets topic (check topicKeysPattern/topicValuesPattern config)
2. Upgrade kafka-ui to a version supporting the new schema version written by your Kafka broker
3. Verify the message is actually an __consumer_offsets key and not application data

ByteBuffer bb = ByteBuffer.wrap(data); short v = bb.getShort(); if (v < 0 || v > 2) return null; // not an __consumer_offsets key

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

try { result = serde.deserialize(...); } catch (IllegalStateException e) { log.warn("unsupported __consumer_offsets key version"); }

When it happens

Trigger: Calling deserializer -> keyDeserializer on a byte array whose first two bytes (big-endian short) decode to a version outside {0,1,2} for the group metadata/commit key schema.

Common situations: Pointing the builtin ConsumerOffsetsSerde at a topic that is not __consumer_offsets; a future Kafka broker writing a new key schema version the UI doesn't support; corrupted/truncated keys.

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

• Unrecognized 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/205ca2c089f16826. Report an issue: GitHub.

Appendix: source

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

    final Schema commitKeySchema = new Schema(
        new Field("group", Type.STRING, ""),
        new Field("topic", Type.STRING, ""),
        new Field("partition", Type.INT32, "")
    );

    final Schema groupMetadataSchema = new Schema(
        new Field("group", Type.STRING, "")
    );

    return (headers, data) -> {
      var bb = ByteBuffer.wrap(data);
      short version = bb.getShort();
      return new DeserializeResult(
          toJson(
              switch (version) {
                case 0, 1 -> commitKeySchema.read(bb);
                case 2 -> groupMetadataSchema.read(bb);
                default -> throw new IllegalStateException("Unknown group metadata message version: " + version);
              }
          ),
          DeserializeResult.Type.JSON,
          Map.of()
      );
    };
  }

  private Deserializer valueDeserializer() {
    final Schema commitOffsetSchemaV0 =
        new Schema(
            new Field(OFFSET, Type.INT64, ""),
            new Field(METADATA, Type.STRING, ""),
            new Field(COMMIT_TIMESTAMP, Type.INT64, "")
        );

    final Schema commitOffsetSchemaV1 =
        new Schema(

View on GitHub (pinned to 83b5a60cc0)