{"id":"9d1ef4591128b3a7","repo":"apache/kafka","slug":"unknown-share-acquire-mode-id","errorCode":null,"errorMessage":"Unknown share acquire mode id: {}","messagePattern":"Unknown share acquire mode id: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareAcquireMode.java","lineNumber":65,"sourceCode":"            return ShareAcquireMode.valueOf(name.toUpperCase(Locale.ROOT));\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"Invalid value `\" + name + \"` for configuration \" +\n                name + \". The value must either be 'batch_optimized' or 'record_limit'.\");\n        }\n    }\n\n    public byte id() {\n        return id;\n    }\n\n    public static ShareAcquireMode forId(byte id) {\n        switch (id) {\n            case 0:\n                return BATCH_OPTIMIZED;\n            case 1:\n                return RECORD_LIMIT;\n            default:\n                throw new IllegalArgumentException(\"Unknown share acquire mode id: \" + id);\n        }\n    }\n\n    @Override\n    public String toString() {\n        return name;\n    }\n\n    public static class Validator implements ConfigDef.Validator {\n        @Override\n        public void ensureValid(String name, Object value) {\n            String acquireMode = (String) value;\n            try {\n                of(acquireMode);\n            } catch (Exception e) {\n                throw new ConfigException(name, value, \"Invalid value `\" + acquireMode + \"` for configuration \" +\n                    name + \". The value must either be 'batch_optimized' or 'record_limit'.\");\n            }","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareAcquireMode.java#L47-L83","documentation":"Thrown by ShareAcquireMode.forId(byte) when an internal wire/protocol byte identifier does not map to BATCH_OPTIMIZED (0) or RECORD_LIMIT (1). This is a defensive guard on the deserialization path: a byte id arrives from a fetch response, persisted state, or test fixture that is outside the known enum range. It indicates either a protocol mismatch or a forward-incompatible broker/client version pairing.","triggerScenarios":"Calling ShareAcquireMode.forId(id) with a byte value other than 0 or 1. Reached when decoding a ShareFetchResponse or persisted acquire-mode state whose id field was written by a newer or non-conformant producer of the value, or in unit tests that hand-craft a byte id.","commonSituations":"Client and broker are on different Kafka versions where a new acquire-mode id was introduced on one side, a corrupted/transposed byte in a response buffer, or a test that passes an arbitrary constant. Because the value comes from the wire, end users almost never trigger it directly unless they downgrade a client against a newer broker.","solutions":["Align client and broker to the same Kafka release line so the acquire-mode id vocabulary matches.","If hand-decoding protocol data, ensure the byte you pass is one returned by ShareAcquireMode.id() (currently 0 or 1).","Capture the exact byte id in logs and check the broker-side code that produced it for a version skew."],"exampleFix":"// before\nShareAcquireMode mode = ShareAcquireMode.forId((byte) 5);\n\n// after\nShareAcquireMode mode = ShareAcquireMode.forId(ShareAcquireMode.BATCH_OPTIMIZED.id());","handlingStrategy":"validation","validationCode":"// Validate a wire byte id before calling ShareAcquireMode.forId(byte).\npublic static boolean isLegalAcquireModeId(byte id) {\n    return id == (byte) 0   // BATCH_OPTIMIZED\n        || id == (byte) 1;  // RECORD_LIMIT\n}\n\nbyte id = readFromWire();\nif (!isLegalAcquireModeId(id)) {\n    throw new IllegalArgumentException(\"Unsupported share acquire mode id: \" + id);\n}","typeGuard":"// Narrow a byte to a known acquire mode without throwing.\npublic static Optional<ShareAcquireMode> acquireModeForId(byte id) {\n    for (ShareAcquireMode m : ShareAcquireMode.values()) {\n        if (m.id() == id) return Optional.of(m);\n    }\n    return Optional.empty();\n}","tryCatchPattern":"// Only when you cannot inspect the byte first (e.g. third-party payload).\ntry {\n    ShareAcquireMode.forId(id);\n} catch (IllegalArgumentException e) {\n    // Drop the record / close the connection: the producer used an unknown protocol value.\n    log.warn(\"Ignoring record with unknown acquire mode id {}\", id, e);\n}","preventionTips":["This id comes from the wire protocol, not user config — a mismatch means producer/broker version skew; pin compatible versions.","Never hand-roll the byte mapping; always go through ShareAcquireMode.forId so new modes surface as a compile concern.","Log the offending id before discarding; an unknown id often signals an upgraded peer speaking a newer protocol."],"tags":["kafka","share-consumer","protocol","version-skew"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}