apache/kafka · error · ConfigException

Invalid value `{}` for configuration {}. The value must eith

Error message

Invalid value `{}` for configuration {}. The value must either be 'implicit' or 'explicit'.

What it means

Thrown by ShareAcknowledgementMode.Validator.ensureValid (a ConfigDef.Validator) when the configured value of share.acknowledgement.mode cannot be parsed by fromString(). The validator catches the underlying IllegalArgumentException and rethrows it as a org.apache.kafka.common.config.ConfigException with a human-readable message naming the property and listing the allowed values. This is the user-facing error surfaced during KafkaConsumer construction.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareAcknowledgementMode.java:104

    public int hashCode() {
        return Objects.hash(acknowledgementMode);
    }

    @Override
    public String toString() {
        return "ShareAcknowledgementMode{" +
                "mode=" + acknowledgementMode +
                '}';
    }

    public static class Validator implements ConfigDef.Validator {
        @Override
        public void ensureValid(String name, Object value) {
            String acknowledgementMode = (String) value;
            try {
                fromString(acknowledgementMode);
            } catch (Exception e) {
                throw new ConfigException(name, value, "Invalid value `" + acknowledgementMode + "` for configuration " +
                        name + ". The value must either be 'implicit' or 'explicit'.");
            }
        }

        @Override
        public String toString() {
            String values = Arrays.stream(ShareAcknowledgementMode.AcknowledgementMode.values())
                    .map(ShareAcknowledgementMode.AcknowledgementMode::toString).collect(Collectors.joining(", "));
            return "[" + values + "]";
        }
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

Set share.acknowledgement.mode to either "implicit" or "explicit" (case-insensitive, no surrounding whitespace).
Print the resolved config value at startup to catch env-var substitution issues (empty strings, trailing quotes).
Consult the validator's allowed set via its toString() ("[implicit, explicit]") when constructing configs programmatically.

Example fix

# before
share.acknowledgement.mode=${ACK_MODE}   # ACK_MODE was unset -> ""

# after
share.acknowledgement.mode=implicit

Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate the config value before constructing the KafkaConsumer,
// using the same Validator the broker/client would apply.
String mode = props.getProperty("share.acknowledgement.mode");
new ShareAcknowledgementMode.Validator().ensureValid(
    "share.acknowledgement.mode", mode);  // throws ConfigException if invalid
// Safe to build the consumer now.
KafkaConsumer<byte[], byte[]> consumer = new KafkaConsumer<>(props);

Type guard

java.util.function.Predicate<String> isValidAckMode = s ->
    s != null && java.util.Set.of("implicit", "explicit")
        .contains(s.trim().toLowerCase(java.util.Locale.ROOT));

Try / catch

try {
    KafkaConsumer<byte[], byte[]> consumer = new KafkaConsumer<>(props);
} catch (org.apache.kafka.common.config.ConfigException ex) {
    // Configuration value for share.acknowledgement.mode was invalid;
    // correct the property and retry construction.
    if (ex.getMessage().contains("share.acknowledgement.mode")) {
        props.put("share.acknowledgement.mode", "implicit");
    } else {
        throw ex;
    }
}

Prevention

Set share.acknowledgement.mode explicitly in your config map to one of 'implicit' or 'explicit'.
Run the client's ConfigDef Validator during config loading (CI/startup) so bad values fail before runtime.
Keep config in a typed structure (enum or sealed type) rather than raw Strings once parsed.
Catch ConfigException at consumer construction and report which property failed, not just the message.

When it happens

Trigger: Constructing a KafkaShareConsumer (or any consumer with the share.acknowledgement.mode property) with a missing, mistyped, or otherwise invalid value; passing an empty string; passing a value the validator cannot translate to IMPLICIT/EXPLICIT.

Common situations: Typos in config files ("implict", "Explicit " with whitespace, "ACK"); properties loaded from env vars that resolved to empty; migrating configs across Kafka versions where the property name or accepted values changed.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/c9ee3d93531d7f97.json. Report an issue: GitHub.