java.lang.NoClassDefFoundError: jdk/net/Sockets

What the error looks like

The classic client fails when you create it, before any request:

java.lang.NoClassDefFoundError: jdk/net/Sockets
	at org.apache.hc.client5.http.impl.io.DefaultHttpClientConnectionOperator.<clinit>(DefaultHttpClientConnectionOperator.java:87)
	at org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder.createConnectionOperator(PoolingHttpClientConnectionManagerBuilder.java:325)
	at org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder.build(PoolingHttpClientConnectionManagerBuilder.java:344)
	at org.apache.hc.client5.http.impl.classic.HttpClientBuilder.build(HttpClientBuilder.java:859)
	at org.apache.hc.client5.http.impl.classic.HttpClients.createDefault(HttpClients.java:57)
Caused by: java.lang.ClassNotFoundException: jdk.net.Sockets

With the AWS SDK, the same error comes out of S3Client.builder()...build(), through the SDK's Apache 5 client:

java.lang.NoClassDefFoundError: jdk/net/Sockets
	at org.apache.hc.client5.http.impl.io.DefaultHttpClientConnectionOperator.<clinit>(DefaultHttpClientConnectionOperator.java:87)
	at software.amazon.awssdk.http.apache5.internal.conn.SafePoolingHttpClientConnectionManagerBuilder.createConnectionOperator(SafePoolingHttpClientConnectionManagerBuilder.java:207)
	at software.amazon.awssdk.http.apache5.internal.conn.SafePoolingHttpClientConnectionManagerBuilder.build(SafePoolingHttpClientConnectionManagerBuilder.java:222)
	at software.amazon.awssdk.http.apache5.Apache5HttpClient$ApacheConnectionManagerFactory.create(Apache5HttpClient.java:814)
	at software.amazon.awssdk.http.apache5.Apache5HttpClient.createClient(Apache5HttpClient.java:180)
	...
	at software.amazon.awssdk.core.client.builder.SdkDefaultClientBuilder.resolveSyncHttpClient(SdkDefaultClientBuilder.java:480)
	...
	at software.amazon.awssdk.services.s3.DefaultS3ClientBuilder.buildClient(DefaultS3ClientBuilder.java:37)
Caused by: java.lang.ClassNotFoundException: jdk.net.Sockets

NoClassDefFoundError is an Error, not an Exception. A catch (Exception e) around client creation does not catch it. The error appears wherever your code builds the client, which may be long after startup.

Which versions break

On a jlink runtime without jdk.net:

• Classic client: we ran httpclient5 5.5.1 (200), 5.5.2 and 5.6.5 (both fail). We also read the release jars from Maven Central: the reference to jdk/net/Sockets is absent from 5.5 and 5.5.1 and present in 5.5.2 and every 5.6.x release through 5.6.5.
• Async client: the trigger is the httpcore5 version, not httpclient5. httpclient5 5.5.1 with httpcore5 5.4.4 fails too. httpcore5 5.4 through 5.4.4 contain the reference; 5.3.4 and 5.3.6 do not. Another dependency can pull in a newer httpcore5 than the one your httpclient5 declares, so check what your build actually resolves:

mvn dependency:tree -Dincludes=org.apache.httpcomponents.client5,org.apache.httpcomponents.core5

• AWS SDK for Java v2: up to 2.45.0 the default sync HTTP client is apache-client (Apache HttpClient 4), which does not need jdk.net. The SDK's services POM switches the default to apache5-client in 2.46.0 (June 2026), which pins httpclient5 5.6.1 and httpcore5 5.4.2. We ran 2.45.0 (200) and 2.57.2, which resolves httpclient5 5.6.4 and httpcore5 5.4.3 and fails in S3Client.builder().build(). We did not run the versions in between. We ran S3 only. The failing code is in the SDK's shared client builder, so other service clients that use the default sync HTTP client are probably affected too.

Downgrading to httpclient5 5.5.1 with httpcore5 5.3.6 also avoided the error in our runs. We don't recommend it: you give up newer fixes to avoid one line in a jlink command.

With the AWS SDK you could also choose a different HTTP client explicitly in the client builder. That should avoid the Apache 5 client, but we have not tested it. Adding jdk.net is the tested fix.

The async client can hang instead

Not every async client throws. On a runtime without jdk.net, with httpcore5 5.4.3 or 5.4.4 (the versions we ran):

In the hanging cases, the I/O reactor thread dies when it tries to open the connection. Nothing is thrown to your code; the request just waits. The only sign is one stack trace that the JVM prints to stderr:

Exception in thread "httpclient-dispatch-1" java.lang.NoClassDefFoundError: jdk/net/Sockets
	at org.apache.hc.core5.util.ReflectionUtils.<clinit>(ReflectionUtils.java:41)
	at org.apache.hc.core5.reactor.SingleCoreIOReactor.prepareSocket(SingleCoreIOReactor.java:312)
	at org.apache.hc.core5.reactor.SingleCoreIOReactor.processConnectionRequest(SingleCoreIOReactor.java:378)
	at org.apache.hc.core5.reactor.SingleCoreIOReactor.processPendingConnectionRequests(SingleCoreIOReactor.java:355)
	at org.apache.hc.core5.reactor.SingleCoreIOReactor.doExecute(SingleCoreIOReactor.java:151)
	at org.apache.hc.core5.reactor.AbstractSingleCoreIOReactor.execute(AbstractSingleCoreIOReactor.java:92)
	at org.apache.hc.core5.reactor.IOReactorWorker.run(IOReactorWorker.java:44)

That line comes from the JVM's default uncaught-exception handler, not from your logging framework. If you only collect logger output, look in the container's raw stderr. Our requests used get(30, TimeUnit.SECONDS); each one timed out after 30 seconds with TimeoutValueException: Timeout deadline: 30000 MILLISECONDS. A thread dump taken then shows no httpclient-dispatch-1 thread.

The fix is the same: add jdk.net. On a runtime with it, the explicit connection-manager client and the default clients returned 200.

Why jdeps didn't warn you

If you build your module list with jdeps --print-module-deps, it can miss jdk.net. It analyses the jars you give it as targets. With -R it also follows direct references into jars on --class-path, but a jar that nothing references directly is never looked at.

With the AWS SDK 2.57.2 dependencies in one directory (lib/ here), pointing jdeps at the S3 jar printed:

jdeps --print-module-deps --ignore-missing-deps --multi-release 21 --class-path 'lib/*' lib/s3-2.57.2.jar
# java.base,java.xml

Adding -R printed the same. Giving every jar as a target found it:

jdeps --print-module-deps --ignore-missing-deps --multi-release 21 --class-path 'lib/*' lib/*.jar
# java.base,java.logging,java.naming,java.security.jgss,java.xml,jdk.net,jdk.unsupported

We believe the S3 jar has no direct reference to the HTTP client, which the SDK picks up at runtime, so jdeps never follows a path to it. We did not test that explanation. An application jar that only calls the SDK is likely in the same position. Run jdeps over every jar your runtime will load, or add jdk.net by hand.

Will a library update fix it?

Not yet. As of 21 October 2026, 23:40 UTC, HttpClient's master branch still references jdk.net.Sockets directly in DefaultHttpClientConnectionOperator. The latest stable releases on Maven Central are httpclient5 5.6.5 and httpcore5 5.4.4, and both contain the reference. Pre-releases exist (httpclient5 5.7-alpha1, httpcore5 5.5 betas); we have not tested them.

In a related report on an older IBM Java runtime (HTTPCLIENT-2413), an HttpClient maintainer declined to add a reflection-based fallback. Plan on adding the module. Elastic's crawler image fixed the same crash this way in September (elastic/crawler#499).

Receipts

Run on 21 October 2026, 22:34–23:40 UTC, in Docker images eclipse-temurin:21-jdk (sha256:3e3c176ffed168beb42c607be9bc1639b466cf00261a0fb04425562c9d0c5c2b, Temurin 21.0.12.1+1) and eclipse-temurin:25-jdk (sha256:8c0a84ea11c8f6ed52600fc19f1040121f2a162998e9f50a5faebbbad9172dcc, Temurin 25.0.4.1+1), Ubuntu 26.04.1, amd64. The test server was the JDK's own jwebserver on 127.0.0.1, serving an empty S3 bucket list. Programs were compiled with the full JDK and run on two jlink runtimes:

jlink --add-modules java.base,java.logging,java.naming,java.management,java.security.jgss,java.sql,jdk.crypto.ec --no-header-files --no-man-pages --strip-debug --output /rt-min
jlink --add-modules java.base,java.logging,java.naming,java.management,java.security.jgss,java.sql,jdk.crypto.ec,jdk.net --no-header-files --no-man-pages --strip-debug --output /rt-net

The classic-client test, complete:

import org.apache.hc.client5.http.classic.methods.HttpGet;
import org.apache.hc.client5.http.impl.classic.HttpClients;
public class Q1 { public static void main(String[] a) throws Exception {
  try (var c = HttpClients.createDefault()) {
    Integer code = c.execute(new HttpGet("http://127.0.0.1:8000/"), r -> r.getCode());
    System.out.println("STATUS " + code);
  } catch (Throwable t) { t.printStackTrace(); System.exit(1); } } }

The AWS test builds S3Client with no httpClient set (region(US_EAST_1), endpointOverride(http://127.0.0.1:8000), forcePathStyle(true), anonymous credentials) and calls listBuckets(). The async test builds the client each way in the table above, then calls execute(...).get(30, TimeUnit.SECONDS). Dependencies were resolved with Maven 3.9.9 on JDK 21; the JDK 25 run downloaded the same jars directly (same sha256). httpcore5 is the version each httpclient5 POM declares unless the table says otherwise.

Not tested: other JDK vendors and versions, other jlink module lists, AWS SDK versions between 2.45.0 and 2.57.2, service clients other than S3, a get() with no timeout, the HTTP/2 async clients on a runtime with jdk.net (our test server speaks HTTP/1.1 only), application servers and Android.

Source reads, 21 October 2026 (Maven Central, logged out):

• jdk/net/Sockets appears in the class files of httpclient5 5.5.2, 5.6, 5.6.1, 5.6.2, 5.6.3, 5.6.4 and 5.6.5, and of httpcore5 5.4, 5.4.1, 5.4.2, 5.4.3 and 5.4.4. It does not appear in httpclient5 5.5 or 5.5.1, or in httpcore5 5.3.4 or 5.3.6.
• software.amazon.awssdk:services POM: version 2.45.0 lists apache-client, 2.46.0 lists apache5-client (both at line 535). Version 2.46.0 was published on 1 June 2026 and pins httpclient5 5.6.1 and httpcore5 5.4.2, both in the list above.
• httpclient5 5.5.2 was published on 16 December 2025, httpcore5 5.4 on 11 December 2025.