apache/kafka · error · IllegalArgumentException

Expected maxKeyLabel to be non-empty.

Error message

Expected maxKeyLabel to be non-empty.

What it means

Thrown as IllegalArgumentException by the BaseVersionRange constructor when maxKeyLabel is the empty string. Symmetric to the minKeyLabel check: the max label is the map key under which the max version is serialized, so an empty label is rejected up-front to keep round-trip (range -> map -> range) well-defined. Triggered only by direct construction with a bad label, almost always a subclass bug.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/feature/BaseVersionRange.java:73

     * @param maxKeyLabel   Label for the max version key, that's used only to convert to/from a map.
     * @param maxValue      The maximum version value.
     *
     * @throws IllegalArgumentException   If any of the following conditions are true:
     *                                     - (minValue < 0) OR (maxValue < 0) OR (maxValue < minValue).
     *                                     - minKeyLabel is empty, OR, minKeyLabel is empty.
     */
    protected BaseVersionRange(String minKeyLabel, short minValue, String maxKeyLabel, short maxValue) {
        if (minValue < 0 || maxValue < 0 || maxValue < minValue) {
            throw new IllegalArgumentException(
                String.format(
                    "Expected minValue >= 0, maxValue >= 0 and maxValue >= minValue, but received" +
                    " minValue: %d, maxValue: %d", minValue, maxValue));
        }
        if (minKeyLabel.isEmpty()) {
            throw new IllegalArgumentException("Expected minKeyLabel to be non-empty.");
        }
        if (maxKeyLabel.isEmpty()) {
            throw new IllegalArgumentException("Expected maxKeyLabel to be non-empty.");
        }
        this.minKeyLabel = minKeyLabel;
        this.minValue = minValue;
        this.maxKeyLabel = maxKeyLabel;
        this.maxValue = maxValue;
    }

    public short min() {
        return minValue;
    }

    public short max() {
        return maxValue;
    }

    @Override
    public String toString() {
        return String.format(

View on GitHub (pinned to c31c9215e1)

Solutions

1. Verify the maxKeyLabel argument passed to super(...) is a non-empty constant (e.g. "max_version").
2. Guard any externally-supplied label at the boundary before construction.
3. Add a construction test for the subclass to prevent regression.

Example fix

// before
super("min_version", min, "", max);

// after
super("min_version", min, "max_version", max);

String maxKeyLabel = ...;
if (maxKeyLabel == null || maxKeyLabel.isEmpty()) {
    throw new IllegalArgumentException("maxKeyLabel must be non-empty");
}
// safe to proceed

static boolean isValidKeyLabel(String label) {
    return label != null && !label.isEmpty();
}

try {
    // construct the version range with maxKeyLabel
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("maxKeyLabel")) {
        // supply a default label or fail configuration loading
    } else { throw e; }
}

When it happens

Trigger: A subclass passes "" as maxKeyLabel to the BaseVersionRange constructor; a refactor leaves the max label constant unset while min is fine.

Common situations: New feature-range subclass with a typo/dropped constant; refactor replacing constants with computed fields that evaluate to empty at super() time.

Related errors

• Expected minValue >= 0, maxValue >= 0 and maxValue >= minVal
• Expected minKeyLabel to be non-empty.
• %s absent in [%s]
• Topic partitions to assign to cannot have null or empty topi
• RebalanceListener cannot be null

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