FasterXML/jackson-databind · error · IllegalArgumentException

Argument `allowedSchemes` must not be null

Error message

Argument `allowedSchemes` must not be null

What it means

Thrown by the NioPathDeserializer(Collection<String> allowedSchemes) constructor when the allowedSchemes argument is null. This deserializer (for java.nio.file.Path values, introduced in [databind#6129]) explicitly rejects null scheme collections because URI scheme validation requires a definitive set (possibly empty, meaning scheme-less values only, but never null). This is a programmer-error guard, not a data-driven exception.

Source

Thrown at src/main/java/tools/jackson/databind/deser/jdk/JDKFromStringDeserializer.java:402

        public NioPathDeserializer() { this(DEFAULT_ALLOWED_SCHEMES); }

        /**
         * Constructor for specifying URI schemes to accept: matching is done
         * case-insensitively, same as by {@code java.nio.file.Path.of(URI)}.
         *<p>
         * NOTE: for allowed schemes that have no provider installed for the system
         * class loader, look up is also attempted using this thread's context class
         * loader (see [databind#2120]); this is never done for schemes that are not
         * allowed.
         *
         * @param allowedSchemes URI schemes to accept; must not be {@code null}
         *   (but may be empty to only accept scheme-less values)
         */
        public NioPathDeserializer(Collection<String> allowedSchemes) {
            super(Path.class, -1);
            if (allowedSchemes == null) {
                throw new IllegalArgumentException("Argument `allowedSchemes` must not be null");
            }
            _allowedSchemes = allowedSchemes;
        }

        @Override
        public Object _deserialize(String value, DeserializationContext ctxt) throws JacksonException {
            return deserialize(ctxt, value, _allowedSchemes);
        }

        public static Path deserialize(DeserializationContext ctxt, String value,
                Collection<String> allowedSchemes) throws JacksonException {
            // If someone gives us an input with no : at all, treat as local path,
            // instead of failing with invalid URI.

            int colonIx = value.indexOf(':');
            if (colonIx < 0) {
                return Path.of(value);
            }

View on GitHub (pinned to a50c7d2a1d)

Solutions

1. Pass NioPathDeserializer.DEFAULT_ALLOWED_SCHEMES (or Collections.singletonList("file")) when you want the default behavior.
2. Pass an empty collection (Collections.emptyList()) if you only want to accept scheme-less paths.
3. If allowing custom schemes, provide them explicitly as a non-null collection.
4. Use the no-arg NioPathDeserializer() constructor for default behavior.

Example fix

// before
new NioPathDeserializer(null)
// after
new NioPathDeserializer(NioPathDeserializer.DEFAULT_ALLOWED_SCHEMES)

// Never pass null; use default or empty
Collection<String> schemes = (schemes == null)
    ? NioPathDeserializer.DEFAULT_ALLOWED_SCHEMES : schemes;
new NioPathDeserializer(schemes);

Objects.requireNonNull(allowedSchemes, "allowedSchemes must not be null");

When it happens

Trigger: Directly constructing new NioPathDeserializer(null) in custom module code. A custom module or SimpleModule.addDeserializer call that passes null for the schemes parameter. A builder pattern that accidentally leaves the schemes unset.

Common situations: Registering a custom Path deserializer via a module without providing the allowed schemes. Copy-paste from example code that omits the argument. Migration from the default constructor to the custom-schemes constructor where null is passed instead of DEFAULT_ALLOWED_SCHEMES.

Related errors

• Cannot pass null property name
• Trying to resolve a forward reference with id [{}] that wasn
• Cannot call withValueDeserializer() on {}
• Duplicate creator property "%s" (index %s vs %d) for type %s
• Conflicting %s creators: already had %s creator %s, encounte

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