{"record":{"id":"2f0c0a03fee28b50","repo":"apache/dubbo","slug":"the-local-implementation-class-localclass-getname","errorCode":null,"errorMessage":"The local implementation class <localClass.getName()> not implement interface <interfaceClass.getName()>","messagePattern":"The local implementation class <localClass\\.getName\\(\\)> not implement interface <interfaceClass\\.getName\\(\\)>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/config/AbstractInterfaceConfig.java","lineNumber":485,"sourceCode":"     *                       side, it is the {@link Class} of the remote service interface\n     */\n    protected void checkStubAndLocal(Class<?> interfaceClass) {\n        verifyStubAndLocal(local, \"Local\", interfaceClass);\n        verifyStubAndLocal(stub, \"Stub\", interfaceClass);\n    }\n\n    private void verifyStubAndLocal(String className, String label, Class<?> interfaceClass) {\n        if (ConfigUtils.isNotEmpty(className)) {\n            Class<?> localClass = ConfigUtils.isDefault(className)\n                    ? ReflectUtils.forName(interfaceClass.getName() + label)\n                    : ReflectUtils.forName(className);\n            verify(interfaceClass, localClass);\n        }\n    }\n\n    private void verify(Class<?> interfaceClass, Class<?> localClass) {\n        if (!interfaceClass.isAssignableFrom(localClass)) {\n            throw new IllegalStateException(\"The local implementation class \" + localClass.getName()\n                    + \" not implement interface \" + interfaceClass.getName());\n        }\n\n        try {\n            // Check if the localClass a constructor with parameter whose type is interfaceClass\n            ReflectUtils.findConstructor(localClass, interfaceClass);\n        } catch (NoSuchMethodException e) {\n            throw new IllegalStateException(\"No such constructor \\\"public \" + localClass.getSimpleName() + \"(\"\n                    + interfaceClass.getName() + \")\\\" in local implementation class \" + localClass.getName());\n        }\n    }\n\n    private void convertRegistryIdsToRegistries() {\n        computeValidRegistryIds();\n        if (StringUtils.isEmpty(registryIds)) {\n            if (CollectionUtils.isEmpty(registries)) {\n                List<RegistryConfig> registryConfigs = getConfigManager().getDefaultRegistries();\n                registryConfigs = new ArrayList<>(registryConfigs);","sourceCodeStart":467,"sourceCodeEnd":503,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/config/AbstractInterfaceConfig.java#L467-L503","documentation":"Thrown by AbstractInterfaceConfig.verify during stub/local validation (verifyStubAndLocal): the configured local/stub implementation class does not implement the service interface (interfaceClass.isAssignableFrom(localClass) is false). Dubbo requires the stub/local class to be an implementation of the interface so it can substitute for the real service on the client side.","triggerScenarios":"checkStubAndLocal loads the class named by the 'local' or 'stub' attribute (either a custom class or interfaceName+'Local'/'Stub') and checks it implements the interface. If it doesn't, this is thrown. Triggered at export (provider local) or reference (consumer stub) startup.","commonSituations":"The stub/local class implements a different interface or none. A copy-paste pointed stub to the wrong class. The interface name was changed but the stub class wasn't updated. 'local=true'/'stub=true' (default) made Dubbo look for interfaceName+'Local'/'Stub' which doesn't exist or implements the wrong interface.","solutions":["Make the stub/local class implement the exact service interface (implements com.acme.Greeting).","If using default naming (local=true), create a class named <InterfaceName>Local that implements the interface.","Point the stub/local attribute to the correct implementing class.","Remove the local/stub configuration if no client-side stub is needed."],"exampleFix":"// before\npublic class GreetingLocal {} // does not implement Greeting\n<dubbo:service interface=\"com.acme.Greeting\" local=\"true\"/>\n// after\npublic class GreetingLocal implements Greeting {\n    public GreetingLocal() {}\n    // ... implement methods\n}\n<dubbo:service interface=\"com.acme.Greeting\" local=\"true\"/>","handlingStrategy":"validation","validationCode":"void assertStubImplements(Class<?> iface, String stubClassName) throws ClassNotFoundException {\n    Class<?> stub = Class.forName(stubClassName);\n    if (!iface.isAssignableFrom(stub))\n        throw new IllegalStateException(stub + \" must implement \" + iface.getName());\n}","typeGuard":"boolean implementsInterface(Class<?> candidate, Class<?> iface) {\n    return candidate != null && iface.isAssignableFrom(candidate);\n}","tryCatchPattern":"try {\n    serviceConfig.export(); // or reference\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"The local implementation class\") && e.getMessage().contains(\"not implement interface\")) {\n        // make the stub/local class implement the interface\n    }\n    throw e;\n}","preventionTips":["Ensure stub/local classes implement the service interface.","When using local=true/stub=true, create <Interface>Local/<Interface>Stub implementing the interface.","Add a compile-time/test check that stubs implement their interface."],"tags":["config","stub","local","startup","export"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}