apache/dubbo · error · IllegalStateException

ref not allow null!

Error message

ref not allow null!

What it means

Thrown by ServiceConfigBase.checkRef when the service reference (ref) is null at export time. The ref is the actual implementation instance that will serve requests, so it must be non-null before the service is exported.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/config/ServiceConfigBase.java:151

    @Override
    public Boolean getExport() {
        return (export == null && provider != null) ? provider.getExport() : export;
    }

    public boolean shouldDelay() {
        Integer delay = getDelay();
        return delay != null && delay > 0;
    }

    @Override
    public Integer getDelay() {
        return (delay == null && provider != null) ? provider.getDelay() : delay;
    }

    protected void checkRef() {
        // reference should not be null, and is the implementation of the given interface
        if (ref == null) {
            throw new IllegalStateException("ref not allow null!");
        }
        if (!interfaceClass.isInstance(ref)) {
            throw new IllegalStateException("The class "
                    + getClassDesc(ref.getClass()) + " unimplemented interface "
                    + getClassDesc(interfaceClass) + "!");
        }
    }

    private String getClassDesc(Class clazz) {
        ClassLoader classLoader = clazz.getClassLoader();
        return clazz.getName() + "[classloader=" + classLoader.getClass().getName() + "@" + classLoader.hashCode()
                + "]";
    }

    public Optional<String> getContextPath(ProtocolConfig protocolConfig) {
        String contextPath = protocolConfig.getContextpath();
        if (StringUtils.isEmpty(contextPath) && provider != null) {
            contextPath = provider.getContextpath();

View on GitHub (pinned to 3a3043227f)

Solutions

1. Set the implementation instance via serviceConfig.setRef(impl) before exporting.
2. With @DubboService, ensure the annotated class is a concrete Spring bean that gets instantiated.
3. Check for circular dependencies or lazy initialization that delay bean creation past export.

Example fix

// before
ServiceConfig<FooService> service = new ServiceConfig<>();
service.setInterface(FooService.class);
service.export(); // ref is null -> error

// after
service.setRef(new FooServiceImpl());
service.export();

// Ensure ref is set before export
if (serviceConfig.getRef() == null) {
    throw new IllegalStateException(
        "Cannot export service " + serviceConfig.getInterface() + ": implementation (ref) is null");
}
serviceConfig.export();

try {
    serviceConfig.export();
} catch (IllegalStateException e) {
    if ("ref not allow null!".equals(e.getMessage())) {
        serviceConfig.setRef(instantiateImpl(serviceConfig.getInterfaceClass()));
        serviceConfig.export(); // retry after wiring
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling export()/checkRef() on a ServiceConfig whose setRef(...) was never called, or was called with null. Common with programmatic config where the bean wiring is incomplete.

Common situations: Forgetting to set the implementation bean on a programmatic ServiceConfig. Spring bean not yet instantiated when export runs (circular dependency or lazy-init). Annotation-based @Service on an abstract/interface with no concrete bean. Bean removed/disposed before export.

Related errors

• The class <getClassDesc(ref.getClass())> unimplemented inter
• The default protocol has not been initialized.
• Protocol not found: <id>
• Unsupported generic type <generic>
• Invalid configurator rule, please specify at least one param

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