What causes "Unsuitable method ({}) decorated with @JsonCreator (for Enum type {})" in FasterXML/jackson-databind?

Ensure the @JsonCreator static factory takes exactly one parameter and returns the enum type (assignable).

FasterXML/jackson-databind · error · IllegalArgumentException

Unsuitable method ({}) decorated with @JsonCreator (for Enum

Error message

Unsuitable method ({}) decorated with @JsonCreator (for Enum type {})

What it means

Thrown while building an enum key deserializer when a static factory method annotated with @JsonCreator on an enum does not match the required shape: a single-argument method whose return type is assignable to the enum. Any other arity or an incompatible return type is rejected. (A single non-String argument is silently skipped, not thrown.)

Source

Thrown at src/main/java/tools/jackson/databind/deser/BasicDeserializerFactory.java:1283

                    Class<?> returnType = factory.getRawReturnType();
                    // usually should be class, but may be just plain Enum<?> (for Enum.valueOf()?)
                    if (returnType.isAssignableFrom(enumClass)) {
                        // note: mostly copied from 'EnumDeserializer.deserializerForCreator(...)'
                        if (factory.getRawParameterType(0) != String.class) {
                            // [databind#2725]: Should not error out because (1) there may be good creator
                            //   method and (2) this method may be valid for "regular" enum value deserialization
                            // (leaving aside potential for multiple conflicting creators)
//                            throw new IllegalArgumentException("Parameter #0 type for factory method ("+factory+") not suitable, must be java.lang.String");
                            continue;
                        }
                        if (config.canOverrideAccessModifiers()) {
                            ClassUtil.checkAndFixAccess(factory.getMember(),
                                    ctxt.isEnabled(MapperFeature.OVERRIDE_PUBLIC_ACCESS_MODIFIERS));
                        }
                        return JDKKeyDeserializers.constructEnumKeyDeserializer(enumRes, factory, byEnumNamingResolver, byToStringResolver, byIndexResolver);
                    }
                }
                throw new IllegalArgumentException("Unsuitable method ("+factory+") decorated with @JsonCreator (for Enum type "
                        +enumClass.getName()+")");
            }
        }
        // Also, need to consider @JsonValue, if one found
        return JDKKeyDeserializers.constructEnumKeyDeserializer(enumRes, byEnumNamingResolver, byToStringResolver, byIndexResolver);
    }

    /*
    /**********************************************************************
    /* DeserializerFactory impl: find explicitly supported types
    /**********************************************************************
     */

    /**
     * Method that can be used to check if databind module has deserializer
     * for given (likely JDK) type: explicit meaning that it is not automatically
     * generated for POJO.
     *<p>

View on GitHub (pinned to a50c7d2a1d)

Solutions

Ensure the @JsonCreator static factory takes exactly one parameter and returns the enum type (assignable).
If the method isn't meant to be a JSON creator, remove @JsonCreator from it.
For by-name/fromString semantics, name the method fromJson and annotate a single-String-argument factory with @JsonCreator.

Example fix

// before
public enum Color {
    @JsonCreator static Color fromRgb(int r, int g, int b) { ... } // 3 args -> throws
}
// after
public enum Color {
    @JsonCreator static Color fromName(String name) { return Color.valueOf(name.toUpperCase()); }
}

Defensive patterns

Strategy: validation

Validate before calling

// Verify the @JsonCreator factory on the enum conforms before deserialization
Method m = findJsonCreatorFactory(MyEnum.class);
if (m == null
        || m.getParameterCount() != 1
        || !MyEnum.class.isAssignableFrom(m.getReturnType())) {
    throw new IllegalStateException(
        "@JsonCreator on enum must be single-arg and return the enum type");
}

Prevention

Enum @JsonCreator factories: exactly one parameter, return type assignable to the enum.
Reserve @JsonCreator on enums for the canonical fromString(String) factory.
Add a unit test that round-trips every enum value through JSON.

When it happens

Trigger: An enum with a @JsonCreator-annotated static factory that takes zero or 2+ arguments, or whose return type isn't assignable to the enum type.

Common situations: Annotating a convenience factory with @JsonCreator by mistake; an enum with multiple factories where the wrong one got the annotation; a refactor that changed the factory signature (e.g. adding parameters).

Related errors

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