{"record":{"id":"13fa9a7f14e5ee07","repo":"FasterXML/jackson-databind","slug":"unsupported-container-type-when-resolving-ref","errorCode":null,"errorMessage":"Unsupported container type ({}) when resolving reference '{}'","messagePattern":"Unsupported container type \\((.+?)\\) when resolving reference '(.+?)'","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/main/java/tools/jackson/databind/deser/impl/ManagedReferenceProperty.java","lineNumber":142,"sourceCode":"        Iterable<?> iterable = _toIterable(value);\n        for (Object obj : iterable) {\n            if (obj != null) {\n                _backProperty.set(ctxt, obj, instance);\n            }\n        }\n    }\n\n    private Iterable<?> _toIterable(Object value) {\n        if (value instanceof Collection<?> coll) {\n            return coll;\n        }\n        if (value instanceof Map<?,?> map) {\n            return map.values();\n        }\n        if (value instanceof Object[] obs) {\n            return Arrays.asList(obs);\n        }\n        throw new IllegalStateException(\"Unsupported container type (\" + value.getClass().getName()\n                + \") when resolving reference '\" + _referenceName + \"'\");\n    }\n}\n","sourceCodeStart":124,"sourceCodeEnd":146,"githubUrl":"https://github.com/FasterXML/jackson-databind/blob/a50c7d2a1d57234ac4adf70dbd88ac90db6436e4/src/main/java/tools/jackson/databind/deser/impl/ManagedReferenceProperty.java#L124-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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[].","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."],"exampleFix":"// before\n@JsonManagedReference\nprivate Iterable<Child> children; // Iterable is not Collection\n// after\n@JsonManagedReference\nprivate List<Child> children; // List implements Collection","handlingStrategy":"type-guard","validationCode":"// Ensure the managed reference property type is Collection, Map, or Object[]\nif (!Collection.class.isAssignableFrom(rawType)\n        && !Map.class.isAssignableFrom(rawType)\n        && !rawType.isArray()) {\n    // change the property type or remove @JsonManagedReference container flag\n}","typeGuard":"static boolean isValidManagedRefContainer(Class<?> type) {\n    return Collection.class.isAssignableFrom(type)\n        || Map.class.isAssignableFrom(type)\n        || type.isArray();\n}","tryCatchPattern":"try {\n    mapper.readValue(json, Parent.class);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"Unsupported container type\")) {\n        // Fix: change the property type to Collection/Map/Object[]\n    }\n}","preventionTips":["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."],"tags":["jackson","deserialization","managed-reference","container-type","bidirectional"],"analyzedSha":"a50c7d2a1d57234ac4adf70dbd88ac90db6436e4","analyzedAt":"2026-08-06T20:31:51.404Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}