apache/dubbo · error · IllegalArgumentException

Service[<serviceKey>]Target is NULL.

Error message

Service[<serviceKey>]Target is NULL.

What it means

The first ProviderModel constructor (4-arg) validates that the service implementation object (serviceInstance) is non-null before building the provider model. A provider in Dubbo must wrap a real bean instance that will receive RPC invocations, so a null target is a fatal configuration error caught at registration time. The message embeds the serviceKey so you can identify which interface was misconfigured.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/rpc/model/ProviderModel.java:52

public class ProviderModel extends ServiceModel {
    private final List<RegisterStatedURL> urls;
    private final Map<String, List<ProviderMethodModel>> methods = new HashMap<>();

    /**
     * The url of the reference service
     */
    private List<URL> serviceUrls = new ArrayList<>();

    private volatile long lastInvokeTime = 0;

    public ProviderModel(
            String serviceKey,
            Object serviceInstance,
            ServiceDescriptor serviceDescriptor,
            ClassLoader interfaceClassLoader) {
        super(serviceInstance, serviceKey, serviceDescriptor, null, interfaceClassLoader);
        if (null == serviceInstance) {
            throw new IllegalArgumentException("Service[" + serviceKey + "]Target is NULL.");
        }

        this.urls = new CopyOnWriteArrayList<>();
    }

    public ProviderModel(
            String serviceKey,
            Object serviceInstance,
            ServiceDescriptor serviceDescriptor,
            ServiceMetadata serviceMetadata,
            ClassLoader interfaceClassLoader) {
        super(serviceInstance, serviceKey, serviceDescriptor, null, serviceMetadata, interfaceClassLoader);
        if (null == serviceInstance) {
            throw new IllegalArgumentException("Service[" + serviceKey + "]Target is NULL.");
        }

        initMethod(serviceDescriptor.getServiceInterfaceClass());
        this.urls = new ArrayList<>(1);

View on GitHub (pinned to 3a3043227f)

Solutions

1. Ensure the service implementation bean exists and is injected before export: verify the ref passed to ServiceConfig.setRef() / the <dubbo:service ref> attribute resolves to a non-null instance.
2. If exporting programmatically, call serviceConfig.setRef(myServiceImpl) with a concrete, already-constructed object.
3. Check Spring context startup logs for 'no bean named' warnings and fix bean naming/scan-path issues before Dubbo export runs.
4. Add a null-check on the ref in your export bootstrap so the failure is reported with your own context, not deep inside ProviderModel.

Example fix

// before
ServiceConfig<HelloService> sc = new ServiceConfig<>();
sc.setInterface(HelloService.class);
// setRef forgotten -> serviceInstance null -> throws at registration
sc.export();

// after
HelloService impl = applicationContext.getBean(HelloService.class);
ServiceConfig<HelloService> sc = new ServiceConfig<>();
sc.setInterface(HelloService.class);
sc.setRef(impl);
sc.export();

Objects.requireNonNull(serviceInstance, "serviceInstance for " + serviceKey);
new ProviderModel(serviceKey, serviceInstance, serviceDescriptor, interfaceClassLoader);

When it happens

Trigger: Constructing `new ProviderModel(serviceKey, null, serviceDescriptor, interfaceClassLoader)` — i.e. passing a null service bean. Typically reached when a ServiceConfig is exported with a ref that resolved to null (bean not found in the Spring context, lazy-init bean still null, or programmatic export with no setRef).

Common situations: Spring XML/annotation config where @Service(ref=...) or <dubbo:service ref=...> references a bean name that does not exist or was not yet instantiated. Programmatic ServiceConfig.export() where setRef() was never called. AOP/proxy misconfiguration that returns null from the bean factory. Migration where the ref bean id was renamed but the dubbo:service reference was not updated.

Related errors

• Service[${serviceKey}]Target is NULL.
• Provider is not initialized
• Input type ${clazz} doesn't implement the Extension ${type}
• Input type ${clazz} can't be interface!
• Extension name is blank (Extension ${type})!

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/ef7612087f63e1a3. Report an issue: GitHub.