What causes "Acknowledgement mode is null" in apache/kafka?

Set share.acknowledgement.mode explicitly to either "implicit" or "explicit" in consumer config.

apache/kafka · error · IllegalArgumentException

Acknowledgement mode is null

Error message

Acknowledgement mode is null

What it means

Thrown by ShareAcknowledgementMode.fromString(String) when the supplied acknowledgement-mode string is null. The share consumer needs a non-null mode string to resolve it to either IMPLICIT or EXPLICIT; null indicates the caller (typically the config layer) failed to supply a value at all. This is a programmer/config error, not a broker-side condition.

Source

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

            return super.toString().toLowerCase(Locale.ROOT);
        }
    }

    private final AcknowledgementMode acknowledgementMode;

    public static final ShareAcknowledgementMode IMPLICIT = new ShareAcknowledgementMode(AcknowledgementMode.IMPLICIT);
    public static final ShareAcknowledgementMode EXPLICIT = new ShareAcknowledgementMode(AcknowledgementMode.EXPLICIT);

    private ShareAcknowledgementMode(AcknowledgementMode acknowledgementMode) {
        this.acknowledgementMode = acknowledgementMode;
    }

    /**
     * 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);
        }
    }

    /**

View on GitHub (pinned to c31c9215e1)

Solutions

Set share.acknowledgement.mode explicitly to either "implicit" or "explicit" in consumer config.
If constructing configs programmatically, default the value before passing it in (e.g. props.getOrDefault("share.acknowledgement.mode", "implicit")).
Null-check the resolved config value at the boundary and fail with a clearer message before it reaches fromString().

Example fix

// before
String mode = (String) props.get("share.acknowledgement.mode");
ShareAcknowledgementMode.fromString(mode); // throws if key absent

// after
String mode = (String) props.getOrDefault("share.acknowledgement.mode", "implicit");
ShareAcknowledgementMode.fromString(mode);

Defensive patterns

Strategy: validation

Validate before calling

// Validate the acknowledgement mode string before calling fromString.
String mode = /* user/config supplied */ ;
if (mode == null) {
    throw new IllegalArgumentException(
        "share acknowledgement mode must not be null; expected 'implicit' or 'explicit'");
}
ShareAcknowledgementMode.fromString(mode);

Type guard

java.util.function.Function<String, ShareAcknowledgementMode> safeFromString = s -> {
    if (s == null) {
        throw new IllegalArgumentException(
            "Acknowledgement mode is null; expected 'implicit' or 'explicit'");
    }
    return ShareAcknowledgementMode.fromString(s);
};

Try / catch

try {
    ShareAcknowledgementMode.fromString(mode);
} catch (IllegalArgumentException ex) {
    // null or unknown mode; default or prompt the user for a valid value
    ShareAcknowledgementMode fallback = ShareAcknowledgementMode.IMPLICIT;
}

Prevention

Null-check config-derived strings before passing to fromString().
When reading from properties/Map, supply a default with ConfigDef rather than letting null propagate.
Prefer the named constants ShareAcknowledgementMode.IMPLICIT / EXPLICIT when the value is fixed at compile time.

When it happens

Trigger: Calling ShareAcknowledgementMode.fromString(null) directly; the config validator invoking fromString() on a property whose value resolved to null; a Map.get() returning null that was passed straight through.

Common situations: Omitting the share.acknowledgement.mode property while the share consumer requires it; setting the property to a placeholder (e.g. ${ENV}) that resolved to null; programmatic configs built from a Map that did not contain the key.

Related errors

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