What causes "Unknown acknowledge type id: {id}" in apache/kafka?

Upgrade kafka-clients to a version supporting the new acknowledge type.

apache/kafka · error · IllegalArgumentException

Unknown acknowledge type id

Error message

Unknown acknowledge type id: {id}

What it means

Thrown by AcknowledgeType.forId(byte) when the id does not match ACCEPT(1), RELEASE(2), REJECT(3), or RENEW(4). AcknowledgeType enumerates the acknowledgment outcomes a share-group consumer can return when acknowledging fetched records. An unknown id means the client received an unexpected value during (de)serialization of share-group acknowledgment messages.

Solutions

Upgrade kafka-clients to a version supporting the new acknowledge type.
Verify you are passing a value produced by the library (or one of the documented constants), not a hand-coded byte.
Catch IllegalArgumentException around share-group acknowledge calls and report the unsupported id.

Example fix

// before
AcknowledgeType t = AcknowledgeType.forId(rawByte);

// after
try {
    AcknowledgeType t = AcknowledgeType.forId(rawByte);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Unsupported acknowledge id " + rawByte + "; upgrade kafka-clients", e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate against known ids before calling forId
if (rawByte < 1 || rawByte > 4) {
    throw new IllegalArgumentException("Unsupported acknowledge id " + rawByte);
}
AcknowledgeType.forId(rawByte);

Type guard

static boolean isKnownAcknowledgeId(byte id) {
    return id >= 1 && id <= 4;
}

Try / catch

try {
    type = AcknowledgeType.forId(rawByte);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Unsupported acknowledge id; upgrade kafka-clients", e);
}

Prevention

Always pass AcknowledgeType enum values produced by the library, not hand-coded bytes.
Keep the client at or above the broker version when using share groups.
Add integration coverage for share-group acknowledge across versions.

When it happens

Trigger: Calling AcknowledgeType.forId with a byte other than 1-4; receiving a share-group acknowledgment response from a broker using a new acknowledge type unknown to this client.

Common situations: Client older than broker during a rolling upgrade of share-group support; corrupt acknowledgment payload; misuse of the API by passing a raw byte from elsewhere.

Related errors

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/e1dc4c663a545ef5. Report an issue: GitHub.

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/AcknowledgeType.java:72

    /**
     * Returns the AcknowledgeType for the given identifier.
     *
     * @param id The identifier for the acknowledge type
     * @return The corresponding AcknowledgeType
     * @throws IllegalArgumentException If the ID is not recognized
     */
    public static AcknowledgeType forId(byte id) {
        switch (id) {
            case 1:
                return ACCEPT;
            case 2:
                return RELEASE;
            case 3:
                return REJECT;
            case 4:
                return RENEW;
            default:
                throw new IllegalArgumentException("Unknown acknowledge type id: " + id);
        }
    }
}

View on GitHub (pinned to 996fb4585a)