When a High-speed Service Framework (HSF) application starts, it validates that every consumer-side service interface can be loaded. If a required interface class is missing from the classpath, HSF throws the following exception:
java.lang.IllegalArgumentException: HSFApiConsumerBean.ServiceMetadata.ifClazz is nullThis means HSF cannot find the Java interface class that defines the service contract for one of your consumer beans. The sections below walk through the most common causes and how to fix each one.
Cause
The class corresponding to the API operation called by the HSF application fails to load. This typically results from one of the following issues:
| Cause | Description |
|---|---|
| Missing dependency JAR | The module that contains the service interface is not included in your build output |
| Incorrect classpath | The JAR exists but is not on the runtime classpath (common in multi-module projects) |
| Version mismatch | The deployed JAR version does not contain the expected interface class |
| Packaging error | The build produced a JAR that excludes the interface (for example, due to shade or relocation rules) |
Solution
Ensure that the class corresponding to the called API operation can be loaded in the path of the class. Follow the steps below to identify and fix the issue.
Step 1: Find the missing class name
Check your application logs for the full stack trace. The trace points to the consumer bean whose interface class failed to load. Locate the corresponding consumer bean configuration in your Spring XML configuration or Java code to identify the expected interface class name.
Step 2: Verify the class is in the classpath
After you identify the interface class name, confirm it is available at runtime:
Check the dependency: Verify that the module or JAR that defines the interface is declared as a dependency in your
pom.xmlorbuild.gradle.Inspect the build output: Look inside the packaged artifact (WAR, FAT JAR, or Pandora container) to confirm the class file is present:
jar tf your-app.jar | grep YourInterfaceClass
Step 3: Apply the fix
Based on what you find, take the corresponding action:
| Issue | Fix |
|---|---|
| Missing dependency | Add the correct dependency to your build file and rebuild |
| Version mismatch | Align the dependency version with the version that contains the expected interface |
| Packaging exclusion | Review your build plugin configuration (Maven Shade, Spring Boot, or Pandora packaging) to make sure the interface package is not excluded |
After you apply the fix, restart the HSF application and confirm it starts without the IllegalArgumentException.