apache/kafka · error · IllegalArgumentException

%s absent in [%s]

Error message

%s absent in [%s]

What it means

Thrown as IllegalArgumentException by BaseVersionRange.valueOrThrow(key, map) when the given key is absent from the version-range map. valueOrThrow is the helper used by fromMap() factories on subclasses to extract the min/max version: if the deserialized map is missing the expected label (e.g. 'min_version' or 'max_version'), it cannot be reconstructed and this fires. The message prints both the missing key and a dump of the map's actual contents, making schema mismatches obvious.

Source

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

            return false;
        }

        final BaseVersionRange that = (BaseVersionRange) other;
        return Objects.equals(this.minKeyLabel, that.minKeyLabel) &&
            this.minValue == that.minValue &&
            Objects.equals(this.maxKeyLabel, that.maxKeyLabel) &&
            this.maxValue == that.maxValue;
    }

    @Override
    public int hashCode() {
        return Objects.hash(minKeyLabel, minValue, maxKeyLabel, maxValue);
    }

    public static short valueOrThrow(String key, Map<String, Short> versionRangeMap) {
        final Short value = versionRangeMap.get(key);
        if (value == null) {
            throw new IllegalArgumentException(String.format("%s absent in [%s]", key, mapToString(versionRangeMap)));
        }
        return value;
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

1. Compare the key in the error message to the map contents also printed in the message: fix the typo or migrate the schema.
2. When deserializing untrusted/foreign maps, catch IllegalArgumentException and surface a deserialization error rather than crashing.
3. If this occurs during broker-controller handshake, verify both sides run compatible Kafka versions and that no third-party tool mutated the feature map keys.
4. In tests, build the input map through the same constants the subclass uses (e.g. fromMap(range.toMap())) instead of hand-typing keys.

Example fix

// before
Map<String,Short> m = new HashMap<>();
m.put("minVersion", (short) 1);   // wrong key
short min = BaseVersionRange.valueOrThrow("min_version", m);

// after
Map<String,Short> m = new HashMap<>();
m.put("min_version", (short) 1);
m.put("max_version", (short) 3);
short min = BaseVersionRange.valueOrThrow("min_version", m);

Short value = versionRangeMap.get(key);
if (value == null) {
    // key absent: skip, default, or raise a domain-specific error
} else {
    // use value; avoid calling BaseVersionRange.valueOrThrow unless you want exactly its exception
}

static boolean hasVersionKey(java.util.Map<String,Short> map, String key) {
    return key != null && map != null && map.containsKey(key);
}

try {
    short v = BaseVersionRange.valueOrThrow(key, versionRangeMap);
} catch (IllegalArgumentException e) {
    // message: "<key> absent in [...]"
    // the feature/version is unknown; negotiate a safe lower version or skip the feature
}

When it happens

Trigger: Calling valueOrThrow("min_version", map) on a map that lacks that key; subclass fromMap() deserializing a features map whose keys are misspelled, uppercased, or from an incompatible schema; tests passing a hand-built map with one of the entries omitted.

Common situations: Inter-version incompatibility: a newer broker writes feature map keys that an older client does not expect (or vice versa); a forged/hand-edited metadata payload; tests constructing maps with literal keys that don't match the subclass constants.

Related errors

• Expected minValue >= 0, maxValue >= 0 and maxValue >= minVal
• Expected minKeyLabel to be non-empty.
• Expected maxKeyLabel to be non-empty.
• Illegal MetadataRecoveryStrategy: {name}
• Timeout needs to be greater than 0

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