{"id":"cbad42cf90819a3c","repo":"apache/kafka","slug":"invalid-value-for-configuration-the-value-cbad42","errorCode":null,"errorMessage":"Invalid value `{}` for configuration {}. The value must either be 'batch_optimized' or 'record_limit'.","messagePattern":"Invalid value `(.+?)` for configuration (.+?)\\. The value must either be 'batch_optimized' or 'record_limit'\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareAcquireMode.java","lineNumber":49,"sourceCode":"\n    final byte id;\n\n    ShareAcquireMode(final String name, final byte id) {\n        this.name = name;\n        this.id = id;\n    }\n\n    /**\n     * Case-insensitive acquire mode lookup by string name.\n     */\n    public static ShareAcquireMode of(final String name) {\n        if (name == null) {\n            throw new IllegalArgumentException(\"ShareAcquireMode is null\");\n        }\n        try {\n            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    }","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareAcquireMode.java#L31-L67","documentation":"Thrown by ShareAcquireMode.of(String) when the supplied configuration value cannot be matched (case-insensitively) to either BATCH_OPTIMIZED or RECORD_LIMIT. The client validates the 'share.acquire.mode' config so that an unsupported mode cannot propagate into fetch/acquire requests. It surfaces as an IllegalArgumentException because the value is rejected before any enum constant exists.","triggerScenarios":"Calling ShareAcquireMode.of(name) directly with a string other than 'batch_optimized' or 'record_limit' (e.g. 'none', 'earliest', 'batch'). Internally invoked when ConsumerConfig validates the share.acquire.mode property during KafkaShareConsumer construction or when the value is parsed from a properties map/JSON string.","commonSituations":"Typo in share.acquire.mode (e.g. 'batch-optimized' with a hyphen, 'BATCH' shorthand), copying a regular consumer's auto.offset.reset value into a share consumer config, or upgrading from a build that supported a now-removed mode name. Locale-specific uppercase folding also means trailing whitespace or BOM characters are not trimmed and will fail lookup.","solutions":["Set share.acquire.mode to exactly 'batch_optimized' or 'record_limit' (case-insensitive, no surrounding whitespace).","If constructing the enum programmatically, pass one of the documented string names instead of free text.","Validate the value at the config source (properties file / env var) before handing it to KafkaShareConsumer."],"exampleFix":"// before\nprops.put(\"share.acquire.mode\", \"batch-optimized\");\n\n// after\nprops.put(\"share.acquire.mode\", \"batch_optimized\");","handlingStrategy":"validation","validationCode":"// Validate share acquire mode before building the consumer config.\nimport java.util.Locale;\nimport java.util.Set;\nimport java.util.Arrays;\n\nSet<String> ALLOWED = Arrays.stream(ShareAcquireMode.values())\n        .map(e -> e.name.toLowerCase(Locale.ROOT))\n        .collect(java.util.stream.Collectors.toSet());\n\nString acquireMode = props.getProperty(\"share.acquire.mode\"); // or however you source it\nif (acquireMode == null || !ALLOWED.contains(acquireMode.toLowerCase(Locale.ROOT))) {\n    throw new IllegalArgumentException(\n        \"share.acquire.mode must be one of \" + ALLOWED + \" but was: \" + acquireMode);\n}","typeGuard":"// Narrow an arbitrary string to a known ShareAcquireMode before use.\npublic static Optional<ShareAcquireMode> asShareAcquireMode(String raw) {\n    if (raw == null) return Optional.empty();\n    try {\n        return Optional.of(ShareAcquireMode.valueOf(raw.toUpperCase(Locale.ROOT)));\n    } catch (IllegalArgumentException e) {\n        return Optional.empty();\n    }\n}","tryCatchPattern":"// Only if you cannot pre-validate (e.g. user-supplied config map).\ntry {\n    ShareAcquireMode.of(userValue);\n} catch (IllegalArgumentException e) {\n    // message tells the caller the two legal literals; surface to user/config UI.\n    throw new ConfigException(\"share.acquire.mode\", userValue, e.getMessage());\n}","preventionTips":["Source share.acquire.mode from a typed enum in your own configuration object, never from a free-form String.","Centralize the set of allowed values by reflecting over ShareAcquireMode.values() so additions upstream do not silently break you.","Treat acquire-mode config as case-insensitive everywhere (the parser upper-cases), so do the same in your UI/docs."],"tags":["kafka","configuration","share-consumer","validation"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}