FasterXML/jackson-databind · error · IllegalArgumentException

Trying to resolve a forward reference with id [${id}] that w

Error message

Trying to resolve a forward reference with id [${id}] that wasn't previously seen as unresolved.

What it means

Thrown by MapDeserializer.MapReferring.resolveForwardReference when an attempt is made to resolve a forward object-id reference inside a map value using an id that was never registered as pending in the map's accumulator. The MapReferringAccumulator (analogous to CollectionReferringAccumulator) tracks unresolved forward references during Map<K,@JsonIdentityInfo-V> deserialization and iterates its pending list; if the id doesn't match any entry, it throws.

Source

Thrown at src/main/java/tools/jackson/databind/deser/jdk/MapDeserializer.java:1036

            throws JacksonException
        {
            Iterator<MapReferring> iterator = _accumulator.iterator();
            // Resolve ordering after resolution of an id. This means either:
            // 1- adding to the result map in case of the first unresolved id.
            // 2- merge the content of the resolved id with its previous unresolved id.
            Map<Object,Object> previous = _result;
            while (iterator.hasNext()) {
                MapReferring ref = iterator.next();
                if (ref.hasId(id)) {
                    iterator.remove();
                    previous.put(ref.key, value);
                    previous.putAll(ref.next);
                    return;
                }
                previous = ref.next;
            }

            throw new IllegalArgumentException("Trying to resolve a forward reference with id [" + id
                    + "] that wasn't previously seen as unresolved.");
        }

        /**
         * Replace a resolved item in the result map. Called when the bound item
         * is rebound (e.g., builder → built object).
         *
         * @param oldItem Item to replace (Builder)
         * @param newItem Item to replace {@code oldItem} with (Built value)
         *
         * @since 3.2
         */
        public void replaceResolvedItem(Object oldItem, Object newItem) {
            replaceInMap(_result, oldItem, newItem);
            // Pending accumulator entries may also hold the old item if a later
            // forward ref hasn't yet resolved.
            for (MapReferring ref : _accumulator) {
                replaceInMap(ref.next, oldItem, newItem);

View on GitHub (pinned to a50c7d2a1d)

Solutions

1. Ensure the JSON map contains definitions for all referenced object ids in its values.
2. Verify @JsonIdentityInfo configuration is consistent on the map value type.
3. If manually resolving, only use ids from the accumulator's pending reference list.
4. Check for malformed JSON that might introduce unresolved id references.

Example fix

// before: map value references id 7 never defined
{"key":{"ref":7}}
// after: define id 7
{"key":{"ref":7},"other":{"@id":7,"name":"v"}}

// Pre-validate JSON map values contain all referenced object ids
JsonNode tree = mapper.readTree(json);
Set<Object> defined = extractAllIds(tree);
Set<Object> referenced = extractAllRefs(tree);
if (!defined.containsAll(referenced)) {
    throw new IllegalStateException("Unresolved map value ids: " +
        Sets.difference(referenced, defined));
}

try {
    mapper.readValue(json, new TypeReference<Map<String,MyType>>() {});
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("wasn't previously seen as unresolved")) {
        // JSON map is missing an object id definition — fix the data source
    }
}

When it happens

Trigger: Deserializing a Map<K,@JsonIdentityInfo-annotated-V> where JSON contains forward object-id references as map values. The framework attempts to resolve an id that was never registered. Manual resolution with an unknown id. Truncated JSON map missing the referenced object definition.

Common situations: JSON objects (maps) with values that reference object ids never defined in the document. Inconsistent @JsonIdentityInfo between the map value type and referencing types. Changing deserialization order or using partial reads. Mixing @JsonIdentityInfo maps with custom map deserializers.

Related errors

• Trying to resolve a forward reference with id [{}] that wasn
• Could not resolve Object Id [{}] (for {}).
• Trying to resolve a forward reference with id [{}] that wasn
• Trying to resolve a forward reference with id [{}] that wasn
• Could not resolve Object Id [{}] -- unresolved forward-refer

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