[Bug] Native Image Startup Error with ReferenceBean + @DubboReference Configuration

[mattmok]

Pre-check

• I am sure that all the content I provide is in English.

Search before asking

• I had searched in the issues and found no similar issues.

Apache Dubbo Component

Java SDK (apache/dubbo)

Dubbo Version

Dubbo Java 3.3.6, GraalVM 17.0.18+8.1, Spring-boot: 3.5.11, Ubuntu 20.04

Steps to reproduce this issue

Here's a well-structured English issue report for the Apache Dubbo GitHub repository, following open-source community best practices:
markdown

Issue Description

Environment

• Dubbo Version: latest (from dubbo-samples-native-image)
• Native Image Build Tool: GraalVM Native Image
• Build Command: mvn clean package -Pnative native:compile
• Spring Boot Version: compatible with Dubbo samples

Steps to Reproduce

1. Use the official Dubbo native image consumer sample: https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-native-image/dubbo-samples-native-image-consumer
2. Working Scenario: Using @DubboReference directly on field works fine for native image compilation:

   @DubboReference(url = "tri://172.17.0.2:50052?serialization=fastjson2")
   private DemoService demoService;```

Native image builds and runs successfully.
Failing Scenario: Switch to ReferenceBean configuration with @bean + @DubboReference:

@Configuration
public class DemoServiceConfigure {
    @Bean
    @DubboReference(url = "tri://172.17.0.2:50052?serialization=fastjson2")
    public ReferenceBean<DemoService> demoServiceReferenceBean() {
        ReferenceBean<DemoService> referenceBean = new ReferenceBean<>();
        return referenceBean;
    }
}

mvn clean spring-boot:run works normally (JVM mode)
Native image compilation succeeds, but application startup fails with error:
Error Log

Caused by: java.lang.IllegalArgumentException: The interface class of ReferenceBean is not initialized
    at org.apache.dubbo.config.spring.ReferenceBean.afterPropertiesSet(ReferenceBean.java:XXX)
    ...

Root Cause Analysis
I traced the issue to ReferenceAnnotationWithAotBeanPostProcessor:
In processReferenceAnnotatedBeanDefinition() method:
The method correctly sets interfaceClass and interfaceName as attributes on beanDefinition:

beanDefinition.setAttribute("interfaceClass", beanClass);
beanDefinition.setAttribute("interfaceName", interfaceName);

However, it only adds id to beanDefinition.getPropertyValues() (no interface-related properties)
In ReferenceBean.afterPropertiesSet():

if (AotWithSpringDetector.useGeneratedArtifacts()) {
    // Native image mode uses property values (only has "id")
    this.interfaceClass = (Class)beanDefinition.getPropertyValues().get("interfaceClass");
    this.interfaceName = (String)beanDefinition.getPropertyValues().get("interfaceName");
} else {
    // JVM mode uses attributes (works fine)
    this.interfaceClass = (Class)beanDefinition.getAttribute("interfaceClass");
    this.interfaceName = (String)beanDefinition.getAttribute("interfaceName");
}

In native image mode (useGeneratedArtifacts() = true), the code tries to read interfaceClass/interfaceName from propertyValues (which are missing)
This causes interfaceClass to be null, triggering the IllegalArgumentException

What you expected to happen

Expected Behavior

ReferenceBean configuration with @bean + @DubboReference should work for native image builds (same as field-based @DubboReference)
Interface metadata should be properly propagated to ReferenceBean in AOT/native mode
Proposed Fix
Modify ReferenceAnnotationWithAotBeanPostProcessor.processReferenceAnnotatedBeanDefinition() to add interfaceClass and interfaceName to beanDefinition.getPropertyValues() (in addition to attributes):

// Add these lines after setting attributes
beanDefinition.getPropertyValues().add("interfaceClass", beanClass);
beanDefinition.getPropertyValues().add("interfaceName", interfaceName);

This ensures the properties exist in both attribute and property value storage, making them accessible in native image mode.

Anything else

No response

Do you have a (mini) reproduction demo?

• Yes, I have a minimal reproduction demo to help resolve this issue more effectively!

Are you willing to submit a pull request to fix on your own?

• Yes I am willing to submit a pull request on my own!

Code of Conduct

• I agree to follow this project's Code of Conduct

[mattmok]

An annotation used for referencing a Dubbo service.
It is recommended to use @DubboReference on the @bean method in the Java-config class, but not on the fields or setter methods to be injected.
Step 1: Register ReferenceBean in Java-config class:

  @Configuration
  public class ReferenceConfiguration {
      @Bean
      @DubboReference(group = "demo")
      public ReferenceBean<HelloService> helloService() {
          return new ReferenceBean();
      }
 
      @Bean
      @DubboReference(group = "demo", interfaceClass = HelloService.class)
      public ReferenceBean<GenericService> genericHelloService() {
          return new ReferenceBean();
      }
  }

Isn't this style recommended? Could you provide an example?

[zrlw]

Annotation @Bean is not needed as Dubbo will register reference bean automatically, you might define the reference as static final variable for use.

[mattmok]

Annotation @Bean is not needed as Dubbo will register reference bean automatically, you might define the reference as static final variable for use.

I fail to understand this. Could you please provide a code snippet? Isn't the above writing method the officially recommended one?Thank you so much for your help—I really appreciate it!
I tried using this method：

    @DubboReference
    public ReferenceBean<HelloService> helloServiceReferenceBean() {
        ReferenceBean<HelloService> referenceBean = new ReferenceBean<>();
        referenceBean.setInterfaceClass(HelloService.class);
        return referenceBean;
    }

But getting the following error

2026-03-20 08:38:59.998 [main] ERROR org.springframework.boot.SpringApplication - Application run failed
java.lang.IllegalStateException: When using @org.apache.dubbo.config.annotation.DubboReference to inject interface proxy, the method must have only one parameter: public org.apache.dubbo.config.spring.ReferenceBean demo.HelloConfigure.helloServiceReferenceBean()
        at org.apache.dubbo.config.spring.beans.factory.annotation.AbstractAnnotationBeanPostProcessor.lambda$findAnnotatedMethodMetadata$1(AbstractAnnotationBeanPostProcessor.java:203)
        at org.springframework.util.ReflectionUtils.doWithMethods(ReflectionUtils.java:366)
        at org.springframework.util.ReflectionUtils.doWithMethods(ReflectionUtils.java:342)
        at org.apache.dubbo.config.spring.beans.factory.annotation.AbstractAnnotationBeanPostProcessor.findAnnotatedMethodMetadata(AbstractAnnotationBeanPostProcessor.java:180)
        at org.apache.dubbo.config.spring.beans.factory.annotation.AbstractAnnotationBeanPostProcessor.buildAnnotatedMetadata(AbstractAnnotationBeanPostProcessor.java:220)
        at org.apache.dubbo.config.spring.beans.factory.annotation.AbstractAnnotationBeanPostProcessor.findInjectionMetadata(AbstractAnnotationBeanPostProcessor.java:239)
        at org.apache.dubbo.config.spring6.beans.factory.annotation.ReferenceAnnotationWithAotBeanPostProcessor.postProcessBeanFactory(ReferenceAnnotationWithAotBeanPostProcessor.java:119)
        at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(PostProcessorRegistrationDelegate.java:363)
        at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(PostProcessorRegistrationDelegate.java:204)
        at org.springframework.context.support.AbstractApplicationContext.invokeBeanFactoryPostProcessors(AbstractApplicationContext.java:792)
        at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:610)
        at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:146)
        at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:752)
        at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:439)
        at org.springframework.boot.SpringApplication.run(SpringApplication.java:318)
        at org.springframework.boot.SpringApplication.run(SpringApplication.java:1361)
        at org.springframework.boot.SpringApplication.run(SpringApplication.java:1350)

[mattmok]

Dubbo @bean Method AOT Native Image Fix

Date

2026-03-21

Problem

Dubbo @Bean methods returning ReferenceBean fail in GraalVM Native Image with:

UnsupportedFeatureError: Proxy class defined by interfaces [GreetingProvider, EchoService, Destroyable] not found.
Generating proxy classes at runtime is not supported.

Context

• Project: Dubbo microservice demo
• Module: demo-dubbo-consumer
• Issue: Java Config style @Bean + @DubboReference returning ReferenceBean<T> works in JVM but fails in Native Image
• Root Cause: Dubbo's ReferenceAnnotationWithAotBeanPostProcessor only handles field/method injection, not @Bean factory methods

Analysis

Phase 1: Root Cause Investigation

Error Chain

greetingController() constructor
    → greetingProviderReferenceBean bean creation
        → ReferenceBean.afterPropertiesSet()
            → ReferenceBeanManager.addReference()
                → ReferenceBeanSupport.generateReferenceKey()
                    → Proxy.newProxyInstance() [FAILS - Native Image]

Key Discovery 1: AOT Generated Code Missing Properties

Initial AOT Generated Code (BEFORE fix):
target/spring-aot/main/sources/com/tiamaes/cloud/demo/GreetingConfigure__BeanDefinitions.java:

public static BeanDefinition getGreetingProviderReferenceBeanBeanDefinition() {
    RootBeanDefinition beanDefinition = new RootBeanDefinition(ReferenceBean.class);
    beanDefinition.setTargetType(ResolvableType.forClassWithGenerics(ReferenceBean.class, GreetingProvider.class));
    beanDefinition.setFactoryBeanName("greetingConfigure");
    beanDefinition.getPropertyValues().addPropertyValue("id", "greetingProviderReferenceBean");
    // ❌ Missing: interfaceClass, interfaceName, referencePropsJson!
    beanDefinition.setInstanceSupplier(getGreetingProviderReferenceBeanInstanceSupplier());
    return beanDefinition;
}

Why This Matters:

In ReferenceBean.afterPropertiesSet() (AOT mode):

if (AotWithSpringDetector.useGeneratedArtifacts()) {
    // ❌ Gets null - propertyValues doesn't have INTERFACE_CLASS!
    this.interfaceClass = (Class<?>) beanDefinition.getPropertyValues().get(ReferenceAttributes.INTERFACE_CLASS);
    this.interfaceName = (String) beanDefinition.getPropertyValues().get(ReferenceAttributes.INTERFACE_NAME);

    // Later...
    throw new AssertionError("No interface class or name found from attributes");
}

The Missing Attributes:

• INTERFACE_CLASS - Needed to know which service interface to proxy
• INTERFACE_NAME - Fallback for interface class discovery
• referencePropsJson - Contains all reference configuration (group, version, etc.)

Root Cause of Missing Attributes:

ReferenceAnnotationBeanPostProcessor.processReferenceAnnotatedBeanDefinition():

// Sets to attribute (works at runtime, but not serialized to AOT code)
beanDefinition.setAttribute(Constants.REFERENCE_PROPS, attributes);
beanDefinition.setAttribute(ReferenceAttributes.INTERFACE_CLASS, interfaceClass);
beanDefinition.setAttribute(ReferenceAttributes.INTERFACE_NAME, interfaceName);

// Sets to propertyValues
beanDefinition.getPropertyValues().add(ReferenceAttributes.ID, beanName);
// ❌ BUT: In AOT mode, doesn't set INTERFACE_CLASS/INTERFACE_NAME to propertyValues!

The issue is that attribute values are NOT serialized to AOT-generated code. Only propertyValues are serialized.

Key Discovery 2: AOT Generated Code AFTER Fix

After adding property serialization in AOT mode:

beanDefinition.getPropertyValues().addPropertyValue("id", "greetingProviderReferenceBean");
beanDefinition.getPropertyValues().addPropertyValue("interfaceClass", GreetingProvider.class);  // ✅ Added
beanDefinition.getPropertyValues().addPropertyValue("interfaceName", "com.tiamaes.cloud.demo.GreetingProvider");  // ✅ Added

Key Discovery 3: Missing Proxy Registration

Original ReferenceAnnotationWithAotBeanPostProcessor.processAheadOfTime():

AnnotatedInjectionMetadata metadata = findInjectionMetadata(beanDefinition, beanClass, beanName);
// Only finds @DubboReference on fields/methods, NOT on @Bean methods

For @Bean methods returning ReferenceBean:

• beanClass = ReferenceBean.class (not the configuration class)
• findInjectionMetadata(ReferenceBean.class) returns empty metadata
• No proxy hints registered
• Native Image can't create proxies at runtime

Phase 2: Pattern Analysis

Working Pattern (Field Injection)

@Configuration
public class GreetingConfigure {
    @DubboReference
    public GreetingProvider greetingProvider;  // ✅ Works
}

• findInjectionMetadata() scans fields in GreetingConfigure class
• Finds @DubboReference annotation
• Registers proxy hints correctly

Failing Pattern (@bean Method)

@Configuration
public class GreetingConfigure {
    @Bean
    @DubboReference
    public ReferenceBean<GreetingProvider> greetingProviderReferenceBean() {
        return new ReferenceBean<>();  // ❌ Fails in Native Image
    }
}

• @DubboReference is on the @Bean method, not a field
• findInjectionMetadata(ReferenceBean.class) scans ReferenceBean class (not GreetingConfigure)
• Returns empty metadata
• No proxy hints registered

Dubbo's Existing Detection

isAnnotatedReferenceBean(beanDefinition) exists and detects this pattern:

• Checks if factory method returns ReferenceBean
• Used in runtime postProcessBeanFactory() processing
• NOT used in AOT processAheadOfTime() processing

Phase 3: Hypothesis and Testing

Hypothesis: Extend processAheadOfTime() to handle @Bean methods returning ReferenceBean

Solution:

1. Add isAnnotatedReferenceBean() check in processAheadOfTime()
2. Extract interface class from beanDefinition
3. Create BeanMethodAotContribution to register proxy hints

Implementation

File 1: ReferenceAnnotationBeanPostProcessor.java

Location: demo-dubbo-consumer/src/main/java/org/apache/dubbo/config/spring/beans/factory/annotation/

Change: Add AOT property serialization in processReferenceAnnotatedBeanDefinition()

// For AOT mode: also set INTERFACE_CLASS, INTERFACE_NAME and referencePropsJson to propertyValues
// ReferenceBean.afterPropertiesSet() reads from propertyValues in AOT mode
if (AotWithSpringDetector.isAotProcessing()) {
    Class interfaceClass = (Class) beanDefinition.getAttribute(ReferenceAttributes.INTERFACE_CLASS);
    String interfaceName = (String) beanDefinition.getAttribute(ReferenceAttributes.INTERFACE_NAME);
    if (interfaceClass != null) {
        beanDefinition.getPropertyValues().add(ReferenceAttributes.INTERFACE_CLASS, interfaceClass);
    }
    if (interfaceName != null) {
        beanDefinition.getPropertyValues().add(ReferenceAttributes.INTERFACE_NAME, interfaceName);
    }
    // Serialize REFERENCE_PROPS to JSON so it's available in native image runtime
    if (beanDefinition.hasAttribute(Constants.REFERENCE_PROPS)) {
        Map<String, Object> referenceProps = (Map<String, Object>) beanDefinition.getAttribute(Constants.REFERENCE_PROPS);
        beanDefinition.getPropertyValues().add("referencePropsJson", JsonUtils.toJson(referenceProps));
    }
}

File 2: ReferenceAnnotationWithAotBeanPostProcessor.java

Location: demo-dubbo-consumer/src/main/java/org/apache/dubbo/config/spring6/beans/factory/annotation/

Changes:

1. New Imports

import java.lang.annotation.Annotation;
import java.util.Collections;
import java.util.Map;
import org.springframework.beans.PropertyValues;
import org.springframework.core.type.MethodMetadata;
import org.springframework.lang.NonNull;

2. Modified processAheadOfTime() Method

@Override
@Nullable
public BeanRegistrationAotContribution processAheadOfTime(RegisteredBean registeredBean) {
    Class<?> beanClass = registeredBean.getBeanClass();
    String beanName = registeredBean.getBeanName();
    RootBeanDefinition beanDefinition = registeredBean.getMergedBeanDefinition();

    // Check if this is a @Bean method returning ReferenceBean (Java Config style)
    if (isAnnotatedReferenceBean(beanDefinition)) {
        Class<?> interfaceClass = getInterfaceClassFromBeanDefinition(beanDefinition);
        if (interfaceClass != null) {
            return new BeanMethodAotContribution(interfaceClass);
        }
    }

    AnnotatedInjectionMetadata metadata = findInjectionMetadata(beanDefinition, beanClass, beanName);
    if (!CollectionUtils.isEmpty(metadata.getFieldElements())
            || !CollectionUtils.isEmpty(metadata.getMethodElements())) {
        return new AotContribution(beanClass, metadata, getAutowireCandidateResolver());
    }
    return null;
}

3. New Helper Method

@Nullable
private Class<?> getInterfaceClassFromBeanDefinition(RootBeanDefinition beanDefinition) {
    // Try propertyValues first (set by processReferenceAnnotatedBeanDefinition in AOT mode)
    Object interfaceClass = beanDefinition.getPropertyValues().get("interfaceClass");
    if (interfaceClass instanceof Class) {
        return (Class<?>) interfaceClass;
    }
    // Fallback to attribute
    interfaceClass = beanDefinition.getAttribute("interfaceClass");
    if (interfaceClass instanceof Class) {
        return (Class<?>) interfaceClass;
    }
    return null;
}

4. New Inner Class: BeanMethodAotContribution

private static class BeanMethodAotContribution implements BeanRegistrationAotContribution {

    private final Class<?> interfaceClass;

    BeanMethodAotContribution(Class<?> interfaceClass) {
        this.interfaceClass = interfaceClass;
    }

    @Override
    public void applyTo(GenerationContext generationContext, @NonNull BeanRegistrationCode beanRegistrationCode) {
        registerProxyHints(generationContext.getRuntimeHints());
    }

    private void registerProxyHints(RuntimeHints hints) {
        hints.proxies().registerJdkProxy(interfaceClass, EchoService.class, Destroyable.class);
        hints.proxies().registerJdkProxy(interfaceClass, EchoService.class, Destroyable.class, GenericService.class);
        hints.proxies().registerJdkProxy(interfaceClass, EchoService.class, Destroyable.class,
            SpringProxy.class, Advised.class, DecoratingProxy.class);
        hints.proxies().registerJdkProxy(interfaceClass, GenericService.class, Destroyable.class,
            SpringProxy.class, Advised.class, DecoratingProxy.class);
        hints.reflection().registerType(TypeReference.of(interfaceClass), MemberCategory.INVOKE_PUBLIC_METHODS);
        AotUtils.registerSerializationForService(interfaceClass, hints);
    }
}

Generated AOT Configuration

After running mvn spring-boot:process-aot, the following proxy configurations are generated in:
target/spring-aot/main/resources/META-INF/native-image/com.tiamaes.cloud.demo/demo-dubbo-consumer/proxy-config.json

[
  ["com.tiamaes.cloud.demo.GreetingProvider",
   "org.apache.dubbo.rpc.service.EchoService",
   "org.apache.dubbo.rpc.service.Destroyable"],

  ["com.tiamaes.cloud.demo.GreetingProvider",
   "org.apache.dubbo.rpc.service.EchoService",
   "org.apache.dubbo.rpc.service.Destroyable",
   "org.apache.dubbo.rpc.service.GenericService"],

  ["com.tiamaes.cloud.demo.GreetingProvider",
   "org.apache.dubbo.rpc.service.EchoService",
   "org.apache.dubbo.rpc.service.Destroyable",
   "org.springframework.aop.SpringProxy",
   "org.springframework.aop.framework.Advised",
   "org.springframework.core.DecoratingProxy"],

  ["com.tiamaes.cloud.demo.GreetingProvider",
   "org.apache.dubbo.rpc.service.GenericService",
   "org.apache.dubbo.rpc.service.Destroyable",
   "org.springframework.aop.SpringProxy",
   "org.springframework.aop.framework.Advised",
   "org.springframework.core.DecoratingProxy"]
]

Test Plan

1. Build: mvn clean package -DskipTests
2. Run:

   java --add-opens=java.base/java.lang=ALL-UNNAMED \
        --add-opens=java.base/java.util=ALL-UNNAMED \
        --add-opens=java.base/java.time=ALL-UNNAMED \
        --add-opens=java.base/java.text=ALL-UNNAMED \
        --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED \
        -jar target/demo-dubbo-consumer-1.0.0-SNAPSHOT-executable.jar

3. Verify: Check logs/server.log for successful startup
4. Test: Call /greeting?name=World endpoint

Notes

Why This Approach Works

1. Reuses Existing Infrastructure: Uses existing isAnnotatedReferenceBean() detection
2. Minimal Changes: Only adds new code path for @Bean methods, doesn't affect field/method injection
3. Consistent with Existing Patterns: Follows same proxy registration pattern as AotContribution
4. Type-Safe: Uses extracted interfaceClass instead of trying to create synthetic AnnotatedInjectElement

Alternative Approaches Considered

1. Creating Synthetic AnnotatedInjectElement: Failed due to AnnotatedMethodElement requiring a reflection Method object (we only have MethodMetadata)
2. Modifying AotContribution: Would require handling empty metadata differently
3. Manual Proxy Configuration: Works but requires manual maintenance

Potential Dubbo Community Contribution

This could be contributed back to Apache Dubbo as a bug fix for ReferenceAnnotationWithAotBeanPostProcessor. The @Bean method pattern with @DubboReference is a valid use case that should be supported in Native Image.

Related Files

• Demo Service Interface: demo-common/src/main/java/com/tiamaes/cloud/demo/GreetingProvider.java
• Consumer Config: demo-dubbo-consumer/src/main/java/com/tiamaes/cloud/demo/GreetingConfigure.java
• Consumer Controller: demo-dubbo-consumer/src/main/java/com/tiamaes/cloud/demo/GreetingController.java

References

• Dubbo Source: /home/chen/Projects/dubbo
• Original Error: UnsupportedFeatureError: Proxy class defined by interfaces...
• GraalVM Native Image Proxy Configuration: -H:DynamicProxyConfigurationResources