FasterXML/jackson-databind · error · IllegalStateException

Unsupported container type (${value.getClass().getName()}) w

Error message

Unsupported container type (${value.getClass().getName()}) when resolving reference '${_referenceName}'

What it means

ManagedReferenceProperty resolves a @JsonManagedReference/@JsonBackReference pair where the managed side is a container; _toIterable only accepts Collection, Map, or Object[]. If the resolved value is any other type (a Stream, Iterable-but-not-Collection, single object, or custom container), the back reference cannot be injected and an IllegalStateException is raised.

Source

Thrown at src/main/java/tools/jackson/databind/deser/impl/ManagedReferenceProperty.java:142

        Iterable<?> iterable = _toIterable(value);
        for (Object obj : iterable) {
            if (obj != null) {
                _backProperty.set(ctxt, obj, instance);
            }
        }
    }

    private Iterable<?> _toIterable(Object value) {
        if (value instanceof Collection<?> coll) {
            return coll;
        }
        if (value instanceof Map<?,?> map) {
            return map.values();
        }
        if (value instanceof Object[] obs) {
            return Arrays.asList(obs);
        }
        throw new IllegalStateException("Unsupported container type (" + value.getClass().getName()
                + ") when resolving reference '" + _referenceName + "'");
    }
}

View on GitHub (pinned to 87876ca5c0)

Solutions

1. Type the managed-reference container as a concrete Collection (List/Set), Map, or Object[] so _toIterable can handle it.
2. If using a third-party collection, convert it to a java.util collection before serialization, or annotate as a non-container reference.
3. Ensure _isContainer (set from the declared type at introspection) matches the runtime type of the value.
4. For Iterable-only types, switch to List or implement Collection.

Example fix

// before
@JsonManagedReference
private FluentIterable<Item> items; // not a Collection -> throws on resolve

// after
@JsonManagedReference
private List<Item> items; // Collection is supported

Object v = managedFieldValue;
if (!(v instanceof Collection || v instanceof Map || v instanceof Object[])) {
    throw new IllegalStateException("Unsupported managed-ref container: " + v.getClass());
}

static boolean isSupportedManagedContainer(Object v) {
    return v instanceof Collection<?> || v instanceof Map<?,?> || v instanceof Object[];
}

try { mapper.readValue(json, Parent.class); }
catch (IllegalStateException e) {
    if (e.getMessage().contains("Unsupported container type")) {
        // retype the managed-ref field as List/Set/Map/Object[]
    } else throw e;
}

When it happens

Trigger: A @JsonManagedReference field typed as Iterable (not a Collection), Stream, Iterator, or a custom aggregate; a single (non-container) value marked as a managed reference container mismatch with the actual data; mis-typing the back reference relationship on a non-standard collection.

Common situations: Using guava ImmutableList (ok, it's a Collection) vs guava FluentIterable (not a Collection -> fails); Stream-typed fields; domain types that wrap a collection but do not implement Collection/Map; @JsonManagedReference on a property whose runtime value is a single element where _isContainer was set true.

Related errors

• Cannot handle managed/back reference '{}': type: value deser
• AnnotationIntrospector returned Converter definition of type
• AnnotationIntrospector returned Class {}; expected Class<Con
• Invalid abstract type resolution from {} to {}: latter is no
• Only support `JavaType` implementation of `ResolvedType`, no

AI-assisted analysis of FasterXML/jackson-databind@87876ca5c0 (2026-08-11). Data as JSON: /api/errors/42190d6472f5b030. Report an issue: GitHub.