What causes "Service[${serviceKey}]Target is NULL." in apache/dubbo?

Pass a non-null service instance: ensure ServiceConfig.setRef(...) or the equivalent bean lookup returns the concrete implementation before export.

apache/dubbo · error · IllegalArgumentException

Service[${serviceKey}]Target is NULL.

Error message

Service[${serviceKey}]Target is NULL.

What it means

The second ProviderModel constructor (5-arg with ServiceMetadata) performs the same non-null serviceInstance guard. It is the path used when a ServiceMetadata object is supplied alongside the service descriptor. As with the other constructors, a null target bean cannot back an exported provider and is rejected immediately rather than failing later during an invocation.

Source

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

            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);
    }

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

View on GitHub (pinned to 3a3043227f)

Solutions

Pass a non-null service instance: ensure ServiceConfig.setRef(...) or the equivalent bean lookup returns the concrete implementation before export.
Validate the ref in your bootstrap: `Objects.requireNonNull(ref, "ref for " + serviceKey)` before constructing/exporting.
Fix the Spring/bean wiring so the referenced bean is instantiated and injected prior to Dubbo export.

Example fix

// before
Object ref = null; // bean lookup failed silently
new ProviderModel(key, ref, descriptor, metadata, loader); // throws

// after
Object ref = Objects.requireNonNull(beanFactory.getBean(implClass), "missing impl for " + key);
new ProviderModel(key, ref, descriptor, metadata, loader);

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Validate the ref bean is non-null before constructing the ProviderModel with ServiceMetadata.
Ensure the Spring context that owns the ServiceMetadata has refreshed and wired the impl bean.
Add an explicit null-check in your export path to surface a clearer error.

When it happens

Trigger: Calling `new ProviderModel(serviceKey, null, serviceDescriptor, serviceMetadata, interfaceClassLoader)`. Reached when ServiceConfig carrying a ServiceMetadata exports with a ref that resolved to null.

Common situations: Same root causes as 362 (null service ref), but specifically when the metadata-bearing constructor is selected — typically when an integrator or framework path attaches a ServiceMetadata to the registration. Bean wiring mistakes, lazy beans, and programmatic export without setRef are the usual triggers.

Related errors

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