What causes "The interface class is not a interface!" in apache/dubbo?

Pass the interface type that the provider implements, not the implementation class.

apache/dubbo · error · IllegalStateException

The interface class <interfaceClass> is not a interface!

Error message

The interface class <interfaceClass> is not a interface!

What it means

Thrown by ReferenceConfigBase.setInterface when the provided Class is not actually a Java interface. Dubbo references (consumers) must target an interface, not a concrete or abstract class. The check rejects the assignment before storing the class.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/config/ReferenceConfigBase.java:257

                return Class.forName(interfaceName, true, classLoader);
            }
        } catch (ClassNotFoundException t) {
            throw new IllegalStateException(t.getMessage(), t);
        }
        return null;
    }

    @Override
    protected void postProcessAfterScopeModelChanged(ScopeModel oldScopeModel, ScopeModel newScopeModel) {
        super.postProcessAfterScopeModelChanged(oldScopeModel, newScopeModel);
        if (this.consumer != null && this.consumer.getScopeModel() != getScopeModel()) {
            this.consumer.setScopeModel(getScopeModel());
        }
    }

    public void setInterface(Class<?> interfaceClass) {
        if (interfaceClass != null && !interfaceClass.isInterface()) {
            throw new IllegalStateException("The interface class " + interfaceClass + " is not a interface!");
        }
        setInterface(interfaceClass == null ? null : interfaceClass.getName());
        this.interfaceClass = interfaceClass;
        if (getInterfaceClassLoader() == null) {
            setInterfaceClassLoader(interfaceClass == null ? null : interfaceClass.getClassLoader());
        } else {
            if (interfaceClass != null) {
                try {
                    if (!interfaceClass.equals(
                            Class.forName(interfaceClass.getName(), false, getInterfaceClassLoader()))) {
                        // interfaceClass is not visible from origin classloader, override the classloader from
                        // interfaceClass into referenceConfig
                        setInterfaceClassLoader(interfaceClass.getClassLoader());
                    }
                } catch (ClassNotFoundException e) {
                    // class not found from origin classloader, override the classloader from interfaceClass into
                    // referenceConfig
                    setInterfaceClassLoader(interfaceClass.getClassLoader());

View on GitHub (pinned to 3a3043227f)

Solutions

Pass the interface type that the provider implements, not the implementation class.
If you genuinely need a non-interface type, reconsider the design — Dubbo references require interfaces.
Use setInterface(String) with the interface's fully-qualified name if you only have the name.

Example fix

// before
referenceConfig.setInterface(FooServiceImpl.class); // concrete class

// after
referenceConfig.setInterface(FooService.class); // the interface

Defensive patterns

Strategy: type-guard

Validate before calling

// Ensure the class is an interface before assigning
if (interfaceClass != null && !interfaceClass.isInterface()) {
    throw new IllegalArgumentException(
        interfaceClass + " is not an interface; references require an interface type");
}
referenceConfig.setInterface(interfaceClass);

Type guard

static boolean isJavaInterface(Class<?> c) {
    return c != null && c.isInterface();
}

Try / catch

try {
    referenceConfig.setInterface(clazz);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("is not a interface")) {
        // locate the interface the class implements and use that
    }
    throw e;
}

Prevention

Always pass the service interface type, never the implementation class, to references.
When using generics, ensure the type parameter is bound to an interface.

When it happens

Trigger: Calling setInterface(Class) with a class that returns false for Class.isInterface() (i.e. a concrete class, abstract class, enum, record, etc.).

Common situations: Pointing a ReferenceConfig at an implementation class instead of the interface. Accidentally using a concrete service class as the reference type. Generics/typing slip where a class token of the impl is passed. Migrating code that previously used a class-based API.

Related errors

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