What causes "Unsupported container type ({}) when resolving reference '{}'" in FasterXML/jackson-databind?

Ensure the managed reference property is typed as Collection, Map, or Object[] if it is a container reference.

FasterXML/jackson-databind · error · IllegalStateException

Unsupported container type ({}) when resolving reference '{}

Error message

Unsupported container type ({}) when resolving reference '{}'

What it means

Thrown by ManagedReferenceProperty._toIterable when the value assigned to a managed reference property (the 'forward' side of a @JsonManagedReference/@JsonBackReference pair) is not a recognized container type. The method only accepts Collection, Map, or Object[] — any other type (e.g., a plain POJO, a Set subtype that fails instanceof, or a scalar) triggers this IllegalStateException. This happens during back-reference population when iterating container elements.

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 a50c7d2a1d)

Solutions

Ensure the managed reference property is typed as Collection, Map, or Object[] if it is a container reference.
If using a custom wrapper, make it implement Collection or Map so _toIterable can handle it.
If the relationship is one-to-one (not a container), check that the reference was not incorrectly flagged as container by the introspector.
Avoid using Iterable directly — use List or Set which extend Collection.

Example fix

// before
@JsonManagedReference
private Iterable<Child> children; // Iterable is not Collection
// after
@JsonManagedReference
private List<Child> children; // List implements Collection

Defensive patterns

Strategy: type-guard

Validate before calling

// Ensure the managed reference property type is Collection, Map, or Object[]
if (!Collection.class.isAssignableFrom(rawType)
        && !Map.class.isAssignableFrom(rawType)
        && !rawType.isArray()) {
    // change the property type or remove @JsonManagedReference container flag
}

Type guard

static boolean isValidManagedRefContainer(Class<?> type) {
    return Collection.class.isAssignableFrom(type)
        || Map.class.isAssignableFrom(type)
        || type.isArray();
}

Try / catch

try {
    mapper.readValue(json, Parent.class);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Unsupported container type")) {
        // Fix: change the property type to Collection/Map/Object[]
    }
}

Prevention

Use List, Set, or Map for managed reference container properties — not Iterable.
Ensure wrapper types implement Collection if used as managed reference containers.
Validate managed reference property types at configuration time.

When it happens

Trigger: A @JsonManagedReference property annotated as a container (isContainer=true) but whose runtime value is not a Collection, Map, or Object[]. A custom type that wraps a collection but does not implement Collection. A mismatch between the declared property type and the actual deserialized value.

Common situations: Changing a managed reference property from List to a custom wrapper type without updating the @JsonManagedReference/@JsonBackReference configuration. Using Iterable (not Collection) as the property type. Arrays of non-object types being assigned where Jackson expects an Object[].

Related errors

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