FasterXML/jackson-databind · error · IllegalArgumentException

Cannot pass null KeyDeserializers

Error message

Cannot pass null KeyDeserializers

What it means

DeserializerFactoryConfig.withAdditionalKeyDeserializers(KeyDeserializers) registers an additional key-deserializer provider (used for Map keys) and rejects null to fail fast rather than NPE later during map key resolution. Modules that add custom Map key handling call this; a null provider would break the resolution chain silently.

Source

Thrown at src/main/java/tools/jackson/databind/cfg/DeserializerFactoryConfig.java:109

    {
        if (additional == null) {
            throw new IllegalArgumentException("Cannot pass null Deserializers");
        }
        Deserializers[] all = ArrayBuilders.insertInListNoDup(_additionalDeserializers, additional);
        return new DeserializerFactoryConfig(all, _additionalKeyDeserializers, _modifiers,
                _valueInstantiators);
    }

    /**
     * Fluent/factory method used to construct a configuration object that
     * has same key deserializer providers as this instance, plus one specified
     * as argument. Additional provider will be added before existing ones,
     * meaning it has priority over existing definitions.
     */
    public DeserializerFactoryConfig withAdditionalKeyDeserializers(KeyDeserializers additional)
    {
        if (additional == null) {
            throw new IllegalArgumentException("Cannot pass null KeyDeserializers");
        }
        KeyDeserializers[] all = ArrayBuilders.insertInListNoDup(_additionalKeyDeserializers, additional);
        return new DeserializerFactoryConfig(_additionalDeserializers, all, _modifiers,
                _valueInstantiators);
    }

    /**
     * Fluent/factory method used to construct a configuration object that
     * has same configuration as this instance plus one additional
     * deserialiazer modifier. Added modifier has the highest priority (that is, it
     * gets called before any already registered modifier).
     */
    public DeserializerFactoryConfig withDeserializerModifier(ValueDeserializerModifier modifier)
    {
        if (modifier == null) {
            throw new IllegalArgumentException("Cannot pass null modifier");
        }
        ValueDeserializerModifier[] all = ArrayBuilders.insertInListNoDup(_modifiers, modifier);

View on GitHub (pinned to a50c7d2a1d)

Solutions

1. Guard the registration: if (kd != null) cfg.withAdditionalKeyDeserializers(kd).
2. Construct the KeyDeserializers eagerly so it is never null at registration time.
3. Filter nulls from provider lists before the registration loop.
4. In module setup, log/skip a null rather than forwarding it.

Example fix

// before
KeyDeserializers kd = useCustomKeys ? new MyKeyDeserializers() : null;
cfg.withAdditionalKeyDeserializers(kd); // throws
// after
KeyDeserializers kd = useCustomKeys ? new MyKeyDeserializers() : null;
if (kd != null) cfg.withAdditionalKeyDeserializers(kd);

KeyDeserializers kd = ...;
if (kd == null) throw new IllegalArgumentException("KeyDeserializers must not be null");
cfg.withAdditionalKeyDeserializers(kd);

// non-null reference check

try {
    cfg.withAdditionalKeyDeserializers(kd);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Cannot pass null KeyDeserializers")) {
        // skip registration or build a default
    }
    throw e;
}

When it happens

Trigger: Calling config.withAdditionalKeyDeserializers(null); a module registering key deserializers conditionally and passing null when the feature is off; a collection/loop where one KeyDeserializers element is null.

Common situations: Module that adds key deserializers only for certain dataformats and forwards null otherwise; DI-provided KeyDeserializers bean null due to missing dependency; refactoring that left a registration call with a now-nullable field.

Related errors

• Cannot pass null Deserializers
• Cannot pass null modifier
• Cannot pass null resolver
• Module ({}) without defined name
• Module ({}) without defined version

AI-assisted analysis of FasterXML/jackson-databind@a50c7d2a1d (2026-08-06). Data as JSON: /api/errors/a5107e80ce5ea5f4. Report an issue: GitHub.