Resolve HSF-0021 IllegalArgumentException due to non-existent interface class - Enterprise Distributed Application Service

Error message

This error occurs during application startup:

java.lang.IllegalArgumentException: The interface class [com.taobao.hsf.jar.test.HelloWorldService1] specified in ConsumerBean does not exist.

The interfaceName attribute in HSFSpringConsumerBean references an interface class that cannot be found on the classpath.

Note: A similar error, HSF-0014, occurs when the serviceInterface attribute in HSFSpringProviderBean references a nonexistent interface class:
java.lang.IllegalArgumentException: The interface class [com.taobao.hsf.jar.test.HelloWorldService1] specified in ProviderBean does not exist.
Both errors share the same root cause and resolution steps, but apply to different bean types.

Possible causes

Typo in the interface class name. The fully qualified class name specified in interfaceName contains a spelling error or incorrect package path.
Missing dependency. The JAR that contains the interface class is not included in the project dependencies, so the class is unavailable at runtime.
Classpath mismatch. The interface class exists in the project source but is not packaged into the deployment artifact (WAR/JAR), typically due to a build configuration issue.

Solution

Verify the interface class name

Check that the interfaceName value in HSFSpringConsumerBean matches the actual fully qualified name of the interface class.

<!-- Incorrect: typo in the class name -->
<bean id="helloService" class="com.alibaba.boot.hsf.HSFSpringConsumerBean">
    <property name="interfaceName"
              value="com.taobao.hsf.jar.test.HelloWorldService1"/>
</bean>

<!-- Correct: use the exact fully qualified interface name -->
<bean id="helloService" class="com.alibaba.boot.hsf.HSFSpringConsumerBean">
    <property name="interfaceName"
              value="com.taobao.hsf.jar.test.HelloWorldService"/>
</bean>

Replace com.taobao.hsf.jar.test.HelloWorldService with the actual interface class defined in your project.

Check the dependency

Confirm that the JAR containing the interface class is declared as a dependency in your build file.

Maven example:

<dependency>
    <groupId>com.example</groupId>
    <artifactId>hsf-api</artifactId>
    <version>1.0.0</version>
</dependency>

Replace the groupId, artifactId, and version with the values for the module that defines your service interface.

Confirm the class in the build output

After building the project, verify that the interface class is present in the output artifact:

# For a WAR file
jar tf target/<your-app>.war | grep HelloWorldService

# For a JAR file
jar tf target/<your-app>.jar | grep HelloWorldService

If the command returns no results, the class is missing from the build output. Review your build configuration (such as Maven module dependencies or Gradle source sets) to make sure the interface module is included.

Related error codes

Error code	Description
HSF-0014	The interface class specified in the `serviceInterface` attribute of `HSFSpringProviderBean` does not exist. The resolution steps are the same: verify the class name, dependency, and classpath.