FasterXML/jackson-databind · error · IllegalArgumentException

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

Error message

Trying to resolve a forward reference with id [{}] that wasn't previously registered.

What it means

Thrown during deserialization of any-setter properties (@JsonAnySetter) when the library tries to resolve a forward object-id reference using an id that was never registered. The AnySetterReferring.handleResolvedForwardReference method checks hasId(id) and if no matching pending reference exists, it rejects the resolution. This indicates the JSON content references an object id via @JsonIdentityInfo/@JsonIdentityReference that has no corresponding forward-reference record on the any-setter accumulator.

Source

Thrown at src/main/java/tools/jackson/databind/deser/SettableAnyProperty.java:298

        private final SettableAnyProperty _parent;
        private final Object _pojo;
        private final String _propName;

        public AnySetterReferring(SettableAnyProperty parent,
                UnresolvedForwardReference reference, Class<?> type, Object instance, String propName)
        {
            super(reference, type);
            _parent = parent;
            _pojo = instance;
            _propName = propName;
        }

        @Override
        public void handleResolvedForwardReference(DeserializationContext ctxt, Object id, Object value)
            throws JacksonException
        {
            if (!hasId(id)) {
                throw new IllegalArgumentException("Trying to resolve a forward reference with id [" + id.toString()
                        + "] that wasn't previously registered.");
            }
            _parent.set(ctxt, _pojo, _propName, value);
        }
    }

    /*
    /**********************************************************************
    /* Concrete implementations
    /**********************************************************************
     */

    protected static class MethodAnyProperty extends SettableAnyProperty
    {
        public MethodAnyProperty(BeanProperty property,
                AnnotatedMember field, JavaType valueType,
                KeyDeserializer keyDeser,
                ValueDeserializer<Object> valueDeser, TypeDeserializer typeDeser) {

View on GitHub (pinned to a50c7d2a1d)

Solutions

1. Ensure all object ids referenced in the any-setter portion of JSON were previously defined as unresolved forward references earlier in the stream.
2. Verify the @JsonIdentityInfo configuration (generator type and scope) is consistent between the referencing and referenced types.
3. If manually resolving forward references, only call handleResolvedForwardReference with ids that were previously returned during deserialization via handleUnresolvedReference.
4. Inspect the JSON to confirm referenced ids actually exist in the document in the correct order.

Example fix

// before: JSON has forward ref id "5" in any-setter but no object with id "5" defined
{"@id":5,"@type":"Foo"}
// after: ensure the referenced id is defined before or properly registered as forward
{"@id":1,"any":{"ref":{"@id":5,"@type":"Foo"}},"items":[{"@id":5,"name":"x"}]}

// Before resolving, verify the id exists in the ReadableObjectId
ReadableObjectId roid = ctxt.findObjectId(id, generator, resolver);
if (roid == null || !roid.hasId(id)) {
    // skip resolution — id was never registered
    return;
}

Referring ref = ...;
if (ref.hasId(id)) {
    ref.handleResolvedForwardReference(ctxt, id, value);
}

try {
    ref.handleResolvedForwardReference(ctxt, id, value);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("wasn't previously registered")) {
        // log and skip — id mismatch, not a fatal error
        logger.warn("Skipping unregistered forward reference id: {}", id);
    } else { throw e; }
}

When it happens

Trigger: A POJO with both @JsonAnySetter and @JsonIdentityInfo where the JSON contains an object identity reference (forward reference) inside any-setter properties whose id was never declared as unresolved. Calling handleResolvedForwardReference(ctxt, id, value) manually with an id that was not previously encountered during deserialization.

Common situations: Mixing @JsonAnySetter with @JsonIdentityInfo on the same bean, especially with forward references in the unmapped/any-properties. Malformed JSON with object ids that don't match any previously seen ids. Manually invoking UnresolvedForwardReference resolution APIs out of order.

Related errors

• Could not resolve Object Id [{}] (for {}).
• Trying to resolve a forward reference with id [{}] that wasn
• Trying to resolve a forward reference with id [${id}] that w
• Cannot call withValueDeserializer() on {}
• Trying to resolve a forward reference with id [{}] that wasn

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