apache/kafka · error · IllegalArgumentException

Invalid acknowledgement mode: {}

Error message

Invalid acknowledgement mode: {}

What it means

Thrown by the default branch of the switch inside ShareAcknowledgementMode.fromString(String) after valueOf() already succeeded. In practice this branch is unreachable because the only enum constants are IMPLICIT and EXPLICIT, both of which are cased above; the message exists as a defensive guard against future enum constants being added without updating the switch. Hitting it almost always indicates the enum was extended without updating this method.

Source

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

    }

    /**
     * Returns the ShareAcknowledgementMode from the given string.
     */
    public static ShareAcknowledgementMode fromString(String acknowledgementMode) {
        if (acknowledgementMode == null) {
            throw new IllegalArgumentException("Acknowledgement mode is null");
        }

        if (Arrays.asList(Utils.enumOptions(AcknowledgementMode.class)).contains(acknowledgementMode)) {
            AcknowledgementMode mode = AcknowledgementMode.valueOf(acknowledgementMode.toUpperCase(Locale.ROOT));
            switch (mode) {
                case IMPLICIT:
                    return IMPLICIT;
                case EXPLICIT:
                    return EXPLICIT;
                default:
                    throw new IllegalArgumentException("Invalid acknowledgement mode: " + acknowledgementMode);
            }
        } else {
            throw new IllegalArgumentException("Invalid acknowledgement mode: " + acknowledgementMode);
        }
    }

    /**
     * Returns the name of the acknowledgement mode.
     */
    public String name() {
        return acknowledgementMode.toString();
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        ShareAcknowledgementMode that = (ShareAcknowledgementMode) o;

View on GitHub (pinned to c31c9215e1)

Solutions

1. If you added a new AcknowledgementMode constant, add a matching case to the switch in ShareAcknowledgementMode.fromString().
2. Ensure the client JAR on the classpath matches the source (no partial builds / mixed versions).
3. Prefer replacing the switch with a direct return of the resolved mode so future constants are handled automatically.

Example fix

// before
switch (mode) {
    case IMPLICIT: return IMPLICIT;
    case EXPLICIT: return EXPLICIT;
    default: throw new IllegalArgumentException("Invalid acknowledgement mode: " + s);
}

// after
// once AcknowledgementMode has more constants, either add cases or drop the switch:
return new ShareAcknowledgementMode(mode);

// Whitelist accepted mode strings (case-insensitive) before calling fromString.
java.util.Set<String> ALLOWED = java.util.Set.of("implicit", "explicit");
String normalized = mode == null ? null : mode.toLowerCase(java.util.Locale.ROOT);
if (normalized == null || !ALLOWED.contains(normalized)) {
    throw new IllegalArgumentException(
        "Invalid acknowledgement mode: " + mode + "; must be one of " + ALLOWED);
}
ShareAcknowledgementMode.fromString(normalized);

java.util.function.Function<String, ShareAcknowledgementMode> parseMode = s -> {
    String n = s == null ? null : s.trim().toLowerCase(java.util.Locale.ROOT);
    switch (n) {
        case "implicit": return ShareAcknowledgementMode.IMPLICIT;
        case "explicit": return ShareAcknowledgementMode.EXPLICIT;
        default:
            throw new IllegalArgumentException(
                "Invalid acknowledgement mode: " + s + "; expected 'implicit' or 'explicit'");
    }
};

try {
    ShareAcknowledgementMode.fromString(mode);
} catch (IllegalArgumentException ex) {
    // unknown mode; surface a clear validation error to the user/config source
    throw new IllegalArgumentException(
        "share acknowledgement mode '" + mode + "' is not valid; use 'implicit' or 'explicit'", ex);
}

When it happens

Trigger: Adding a new AcknowledgementMode constant without adding a case to the switch in fromString(); reflective or deserialization tricks that yield an enum value outside the cased set.

Common situations: Contributors extending AcknowledgementMode during share-group protocol development and forgetting to update fromString(); running against a patched Kafka JAR where the enum and the switch are out of sync.

Related errors

• Acknowledgement mode is null
• Invalid value `{}` for configuration {}. The value must eith
• ShareAcquireMode is null
• Telemetry is not enabled. Set config `${ConsumerConfig.ENABL
• You must provide a valid ${ConsumerConfig.GROUP_ID_CONFIG} i

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