SDK Troubleshooting
This section describes common errors that you may encounter when attempting to run the agent using your compiled JAR file and the docker-compose.yml file generated by the API Control Plane.
Agent startup errors
Error: JAR File location is wrong
When registering a gateway for a custom Platform Type, the agent will fail to start if the JAR File Location entered during setup is the path directly to the JAR file itself, instead of the path to the directory containing the file. The following errors will appear in the agent logs:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.obsidianagent.plugins.PluginManager: /plugin is not a directory
...
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.o.c.GatewayConfigurationLoader: Unexpected java.lang.Exception when trying to process gateway config: Unsupported gateway type found.
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.o.c.GatewayConfigurationLoader: Exiting application due to invalid configuration, configurations are either empty, or sanity failed
If the directory at the path specified by the JAR File Location does not contain a suitable JAR file, the agent will fail to start. The logs will show that the PluginClassLoader was loaded with nothing:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS - INFO 1 --- [main] c.a.obsidianagent.plugins.PluginManager: Initializing PluginClassLoader with
If the directory at the JAR File Location path contains multiple JAR files, the PluginClassLoader will load the first instance of each class found. There is no guarantee on the order of the files during processing which may lead to unexpected behavior when the classes are loaded. To avoid possible bugs, ensure that the directory contains only a single .jar file with the SDK interface implementations.
Fix:
Regenerate the docker-compose.yml file by navigating to the newly registered Gateway page and clicking Connect Agent, ensuring that the JAR File Location is the path to the directory that the JAR file is in.Alternatively, manually remove the name of the file from the path under volumes in the docker-compose.yml file.
When the JAR File Location is correct, the following will appear in the logs:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS - INFO 1 --- [main] c.a.obsidianagent.plugins.PluginManager: Initializing PluginClassLoader with file:/plugin/controlplane-agent-example-1.2.1-SNAPSHOT.jar
Error: META-INF/services/com.boomi.controlplane.agent.api.GatewayManager file is missing or incorrect
If the META-INF/services/com.boomi.controlplane.agent.api.GatewayManager file is missing, is in the wrong directory, or has the wrong name, the agent will fail to start, and the unsupported type error will appear in the logs:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.o.c.GatewayConfigurationLoader: Unexpected java.lang.Exception when trying to process gateway config: Unsupported gateway type found.
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.o.c.GatewayConfigurationLoader: Exiting application due to invalid configuration, configurations are either empty, or sanity failed
If the META-INF/services/com.boomi.controlplane.agent.api.GatewayManager file contains the correct fully qualified class name of the custom GatewayManager implementation (and only that name), the agent will fail to start. The following will appear in the logs:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS - WARN 1 --- [main] s.c.a.AnnotationConfigApplicationContext: Exception encountered during context initialization - cancelling refresh attempt:
org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'apiDiscoveryConfig' defined in file [/application/BOOT-INF/classes/com/apiida/obsidianagent/apiDiscovery/ApiDiscoveryConfig.class]:
Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'handlerFactoryRegistry': Invocation of init method failed
Fix:
Ensure the META-INF directory exists, the services directory exists within it, and the META-INF/services/com.boomi.controlplane.agent.api.GatewayManager file exists, containing only the fully qualified class name of the custom GatewayManager implementation.
Error: Platform Type Mismatch
The agent will fail to start if the type String supported in the custom implementation of GatewayConfigurationFactory::supports does not exactly match the type in the JSON specification of the custom Platform Type. For example, the following implementation and JSON specification would not match:
@Override
public boolean supports(String type) {
return "example".equals(type);
}
{
"type": "EXAMPLE",
"properties":[
{"fieldName":"username", "description":"identifier used for gateway access"},
{"fieldName":"password", "description":"secret code used to authenticate user"}
]
}
The agent logs will indicate that the implementation does not support the type:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.o.c.GatewayConfigurationLoader: Unexpected java.lang.Exception when trying to process gateway config: Unsupported gateway type found.
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.o.c.GatewayConfigurationLoader: Exiting application due to invalid configuration, configurations are either empty, or sanity failed
Fix:
Edit the implementation of GatewayConfigurationFactory to support the correct type, matching the JSON exactly.Alternatively, delete the custom Platform Type from the API Control Plane and create a new one with a type that matches the implementation. The type cannot be updated after creation of the custom Platform Type, so it must be deleted and recreated in this case.
Error: Required properties are missing
If your implementation of GatewayConfigurationFactory::parseConfiguration requires a certain property and throws an Exception when it is missing, the agent will fail to start if that property is missing from the docker-compose.yml file. The fieldNames of properties in your JSON Specification must include all properties required by your gateway. If the fieldNames are spelled in a way that your implementation does not parse correctly, the error will be thrown on agent startup and will be visible in the logs:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [main] c.a.o.c.GatewayConfigurationLoader: Error when trying to process gateway config: Missing required property 'username'
It is good practice to implement a parseConfiguration method that throws an error when a required property is missing. Errors are easier to identify and isolate when the agent fails fast.
Fix:
Re-upload the JSON Specification for your custom platform type, by clicking Upload New JSON File in the Actions menu on the page for that custom Platform Type, and ensure the fieldNames can be properly parsed by your implementation. Regenerate the docker-compose.yml file by navigating to the page for your Gateway and clicking Connect Agent.
Agent operation errors
Error: Agent is running, but does not appear as connected on ACP
Even if the custom agent is running and successfully connected to the API Control Plane, if DiagnosticsService has not been implemented, the agent may appear offline. The unsupported operation error will appear in the agent logs as soon as it connects:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [ task-5] .a.i.SimpleAsyncUncaughtExceptionHandler Example Test: Unexpected exception occurred invoking async method: public void com.apiida.obsidianagent.jsonRpc.JsonRpcService.handleAsync(kotlin.jvm.functions.Function0)
controlplane-agent-ExampleTest | -
controlplane-agent-ExampleTest | kotlin.NotImplementedError: An operation is not implemented: Not yet implemented
controlplane-agent-ExampleTest | at com.apiida.obsidianagent.diagnostics.DiagnosticsConfig$NotSupportedDiagnosticsService.handleException(DiagnosticsConfig.kt:59) ~[classes/:2026.3.4]
Fix:
Implement both DiagnosticsService methods in your custom agent.
Error: Handler method, Capability, GatewayManager mismatch
If the Capability associated with a given method is not reported, the API Control Plane will throw an error saying that the Capability is not supported by the agent, instead of sending the agent a request for that method. This is visible in the ACP UI, but will not appear in the agent logs because the agent never received the request.
If a Capability is reported by the agent, but the API Control Plane sends a request for a corresponding method that is not implemented by the agent, an UnsupportedOperationException will be thrown by the agent. This will be visible in the agent logs:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [ task-6] c.a.o.jsonRpc.JsonRpcService Example Test: Error during RPC call: Not yet implemented
controlplane-agent-ExampleTest | -
controlplane-agent-ExampleTest | java.lang.UnsupportedOperationException: Not yet implemented
controlplane-agent-ExampleTest | at com.boomi.controlplane.agent.api.apiDiscovery.ApiDiscoveryHandler.discoverApisInEnvironment(ApiDiscoveryHandler.java:62) ~[controlplane-agent-api-1.0.0.jar:na]...
Likewise, if an XHandler and XHandlerFactory are implemented, but the respective GatewayManager::getXFactory method is not implemented, the agent will throw the same UnsupportedOperationException.
Fix:
Review the associations between capabilities and methods above, and report the correct capability with the correct version in your implementation of CapabilityFactory for every handler method that is implemented. Ensure that your GatewayManager implements the getXFactory method for the respective handler.
Error: Null value for DTO field that is annotated non-null
Most DTOs that are return types of handler methods have fields annotated with @NotNull.This means that the API Control Plane is expecting non-null values for these fields and will throw errors if the field is null. These errors will not appear in the agent logs, but will appear on the API Control Plane UI when the agent method is executed. For example, if a DiscoveredApi with a null name is returned by the agent during API discovery, discovery will fail on the UI with an error saying that the name must not be null.
Fix:
Ensure all return values from agent values have non-null values where needed, as indicated by the @NotNull annotations on the SDK DTOs.
Error: Further errors during agent operations
If the agent displays as connected on the API Control Plane, additional errors are likely the result of flaws in the implementation of handler methods. When an error is thrown by a handler method, the process will fail when triggered from API Control Plane, and a job discovery failure error will appear on the UI.
The error will appear in the agent logs as well:
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS - INFO 1 --- [task-4] c.a.o.jsonRpc.JsonRpcService Example Test: request for ApiDiscoveryHandler_discoverApis received with id e798b606-9ceb-46e8-be76-decf2a10fef9 and processId 88e14089-8660-4572-95d1-64f2631b8001
controlplane-agent-ExampleTest | -yyyy-MM-dd HH:mm:ss.SSS -ERROR 1 --- [task-4] c.a.o.jsonRpc.JsonRpcService Example Test: Error during RPC call: Error message.
controlplane-agent-ExampleTest | java.lang.RuntimeException: An exception occurred.
controlplane-agent-ExampleTest | at com.boomi.controlplane.agent.example.apiDiscovery.ExampleApiDiscoveryHandler.discoverApis(ExampleApiDiscoveryHandler.java:35) ~[na:na]
Fix:
The logs will show which handler and which method received a request from API Control Plane, allowing you to narrow down where the error is in the implementation.
