jwtk/jjwt · error · IllegalArgumentException

Map must not be null

Error message

Map must not be null

What it means

IllegalArgumentException thrown by io.jsonwebtoken.lang.Collections.mergePropertiesIntoMap when the target Map argument is null. The Properties source may be null (that case is skipped), but the destination map must be provided.

Source

Thrown at api/src/main/java/io/jsonwebtoken/lang/Collections.java:305

            throw new IllegalArgumentException("Collection must not be null");
        }
        Object[] arr = Objects.toObjectArray(array);
        java.util.Collections.addAll(collection, arr);
    }

    /**
     * Merge the given Properties instance into the given Map,
     * copying all properties (key-value pairs) over.
     * <p>Uses <code>Properties.propertyNames()</code> to even catch
     * default properties linked into the original Properties instance.
     *
     * @param props the Properties instance to merge (may be <code>null</code>)
     * @param map   the target Map to merge the properties into
     */
    @SuppressWarnings("unchecked")
    public static void mergePropertiesIntoMap(Properties props, Map map) {
        if (map == null) {
            throw new IllegalArgumentException("Map must not be null");
        }
        if (props != null) {
            for (Enumeration en = props.propertyNames(); en.hasMoreElements(); ) {
                String key = (String) en.nextElement();
                Object value = props.getProperty(key);
                if (value == null) {
                    // Potentially a non-String value...
                    value = props.get(key);
                }
                map.put(key, value);
            }
        }
    }


    /**
     * Check whether the given Iterator contains the given element.
     *

View on GitHub (pinned to fb71496164)

Solutions

1. Pass a non-null, mutable Map (e.g. new HashMap<>()) as the target
2. Verify argument order: null props is fine, null map is not
3. Initialize the map field before calling the merge

Example fix

// before
Collections.mergePropertiesIntoMap(props, configMap); // configMap is null
// after
Map<String, Object> configMap = new HashMap<>();
Collections.mergePropertiesIntoMap(props, configMap);

if (map == null) {
    map = new HashMap<>();
}
Collections.mergePropertiesIntoMap(props, map);

try {
    Collections.mergePropertiesIntoMap(props, map);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Target map must be initialized before merge", e);
}

When it happens

Trigger: Calling Collections.mergePropertiesIntoMap(props, map) with a null map — e.g. an uninitialized Map field or a null returned from a config lookup.

Common situations: Forgetting to instantiate the target HashMap before merging; a builder/config accessor returning null; swapped arguments.

Related errors

• Collection must not be null
• Class method parameter cannot be null.
• SecretKey byte array cannot be null.
• MAC ${keyType} key cannot be null.

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/685a762ba2ee7cc7. Report an issue: GitHub.