Debugging java.net.spi.InetAddressResolverProvider SPI Failure with OpenTelemetry Java Agent in Spring Boot

Background: The author was asked to investigate why a custom java.net.spi.InetAddressResolverProvider SPI does not work when the application runs on JDK 21 with Spring Boot 3.x and the OpenTelemetry Java agent.

Pre‑conditions for the problem:

JDK version 18 or higher

Spring Boot 3.x

Use of the OpenTelemetry agent ( -javaagent:opentelemetry-javaagent.jar )

The custom InetAddressResolverProvider is intended to replace the built‑in resolver so that a specific domain (e.g., order.service ) can be resolved to a predetermined IP address.

Implementation details:

public class MyAddressResolverProvider extends InetAddressResolverProvider {
    @Override
    public InetAddressResolver get(Configuration configuration) {
        return new MyAddressResolver();
    }
    @Override
    public String name() {
        return "MyAddressResolverProvider Internet Address Resolver Provider";
    }
}

public class MyAddressResolver implements InetAddressResolver {
    public MyAddressResolver() {
        System.out.println("=====MyAddressResolver");
    }
    @Override
    public Stream
lookupByName(String host, LookupPolicy lookupPolicy) throws UnknownHostException {
        if (host.equals("fedora")) {
            return Stream.of(InetAddress.getByAddress(new byte[]{127, 127, 10, 1}));
        }
        return Stream.of(InetAddress.getByAddress(new byte[]{127, 0, 0, 1}));
    }
    @Override
    public String lookupByAddress(byte[] addr) {
        System.out.println("++++++" + addr[0] + " " + addr[1] + " " + addr[2] + " " + addr[3]);
        return "fedora";
    }
}

A service configuration file META-INF/services/java.net.spi.InetAddressResolverProvider containing the fully‑qualified name com.example.demo.MyAddressResolverProvider makes the SPI discoverable.

When the application is packaged as a regular JAR and run with java -jar target/demo-0.0.1-SNAPSHOT.jar , the custom resolver works as expected.

However, after adding the OpenTelemetry agent:

java -javaagent:opentelemetry-javaagent.jar \
    -jar target/demo-0.0.1-SNAPSHOT.jar

the resolution fails with java.net.UnknownHostException . Debugging shows that the class loader used by the agent is a JarLoader that cannot locate the SPI configuration inside the Spring Boot executable JAR (which contains a BOOT-INF directory).

Spring Boot repackaging adds an extra layer ( BOOT-INF ) and modifies the manifest ( Main-Class and Start-Class ). The default ServiceLoader can read resources from a normal JAR, but the agent’s class loader does not understand the Spring Boot layout, so the SPI file is never found.

Additional debugging techniques demonstrated:

Remote debugging with JDWP: java -agentlib:jdwp="transport=dt_socket,server=y,suspend=y,address=5000" -javaagent:opentelemetry-javaagent.jar -jar target/demo-0.0.1-SNAPSHOT.jar

Conditional breakpoints to limit stop points to specific variable states.

The issue was reported to the OpenTelemetry community. The solution is to disable a specific resource loaded by the agent that pre‑emptively loads its own java.net.spi.InetAddressResolverProvider implementation, which overrides the Spring Boot one. After disabling that resource, the custom SPI works correctly.

References:

https://github.com/crossoverJie/demo (demo repository)

https://github.com/TogetherOS/cicada (related SPI example)

Spring Boot Maven plugin documentation

OpenTelemetry Java instrumentation issue #10921