Upgrading your application server is usually a positive step forward—new performance gains, security patches, and new functionalities. However, going from JBoss 7.4 to 8.0 can cause some unexpected hiccups, particularly with JNDI lookups and library class loading. One common headache reported recently is the pesky NamingException coupled with a stubborn ClassNotFoundException. If you’re facing this issue, you’re not alone—and fortunately, there’s a practical way out.
The Scenario: Environment Setup and Behavior Analysis
We experienced this issue while migrating a Java EE-based enterprise application from JBoss EAP (WildFly) 7.4 to version 8.0. Our testing environment was Java 17 (OpenJDK) running on Windows 11 OS. Initially, the problem manifested itself during runtime after deploying the project—a JNDI lookup that previously worked seamlessly simply refused to resolve.
Interestingly, attempts to replicate this setup on a Linux-based distribution produced identical behaviors, signaling it’s not platform-specific but rather a nuanced JBoss library or classpath issue.
Analyzing the NamingException and ClassNotFoundException
Here’s a typical error message encountered after upgrading:
javax.naming.NamingException: WFNAM00018: Naming lookup failed for 'java:/ConnectionFactory'
...
Caused by: java.lang.ClassNotFoundException: javax.jms.ConnectionFactory from [Module "deployment.myApp.war" from Service Module Loader]
If you’ve worked with JBoss or WildFly before, you’re probably familiar with the JNDI (Java Naming and Directory Interface)—it’s essentially the backbone of resource lookup. When a NamingException pops up, it’s typically because the server can’t find the named object you requested in your context or classpath.
The ClassNotFoundException adds another clue; it means the class javax.jms.ConnectionFactory wasn’t found at runtime, even though it’s clearly mapped correctly in JNDI configuration.
Inspecting Our Existing JNDI Lookup Code
To better understand the cause, let’s glance at the original JNDI lookup code:
Context context = new InitialContext();
ConnectionFactory factory = (ConnectionFactory) context.lookup("java:/ConnectionFactory");
Queue myQueue = (Queue) context.lookup("java:/jms/queue/MyQueue");
At first glance, nothing seems wrong—the resource references and JNDI names were untouched during upgrade. This calls for deeper scrutiny. Could it be tied directly with the underlying messaging subsystem or the libraries themselves?
What Changed in the Messaging Subsystem Configuration?
The messaging subsystem for JBoss or WildFly typically resides in your standalone-full.xml file. After an upgrade, it’s quite common to encounter subtle configuration shifts. Thus, our next logical step was to verify the subsystem configuration.
Below is a snippet of typical messaging configuration from WildFly:
<subsystem xmlns="urn:jboss:domain:messaging-activemq:14.0">
<server name="default">
<jms-queue name="MyQueue" entries="[java:/jms/queue/MyQueue]"/>
<connection-factory name="ConnectionFactory" entries="[java:/ConnectionFactory]" connectors="in-vm"/>
</server>
</subsystem>
Despite extensive review, we confirmed that nothing had significantly changed in our messaging configuration itself. If that hasn’t changed, where else might the issue lie?
A Crucial Shift: Transition from javax.jms to jakarta.jms libraries
Here’s a key change between JBoss EAP/WildFly 7.4 and 8.0 you should be aware of—the switch from the older javax.jms packages to the newer jakarta.jms packages. Starting from WildFly 27 and similarly in JBoss 8, the Java EE standard switched fully to the Jakarta EE namespace.
This can explain why our traditional JNDI lookup using javax.jms classes fails post-upgrade. If the server tries to load a Jakarta EE 10-compliant subsystem using the older classes, it naturally results in the “ClassNotFoundException.”
To confirm, let’s update the libraries and dependencies:
- Old Dependency: javax.jms:javax.jms-api
- New Dependency: jakarta.jms:jakarta.jms-api:3.1.0
Updating your pom.xml becomes critical at this stage:
<dependency>
<groupId>jakarta.jms</groupId>
<artifactId>jakarta.jms-api</artifactId>
<version>3.1.0</version>
<scope>provided</scope>
</dependency>
After switching to this dependency, the classes and interfaces from jakarta.jms became visible in our application classpath.
Still, we’re not done yet—your actual Java classes need updating too. Here’s the corrected JNDI lookup snippet:
import jakarta.jms.ConnectionFactory;
import jakarta.jms.Queue;
Context context = new InitialContext();
ConnectionFactory factory = (ConnectionFactory) context.lookup("java:/ConnectionFactory");
Queue myQueue = (Queue) context.lookup("java:/jms/queue/MyQueue");
By updating these imports, your class loader will align correctly with the new Jakarta EE namespace supported by JBoss 8.0.
Troubleshooting Attempted: A Quick Recap
Here’s a quick recap of what helped us finally pinpoint the issue, in case you want to retrace our troubleshooting path:
- Fresh installs and redeployments: Helped rule out any corrupted or incomplete server installations.
- Checking standalone-full.xml: Confirmed configurations were intact.
- Classpath & dependency verification: Led us to identify and migrate from javax.jms to jakarta.jms namespaces.
- Stack Overflow and WildFly forums were also invaluable. Check out the active discussion on this issue on Stack Overflow – WildFly section.
Ultimately, correcting the libraries and classes resulted in stable behavior and resolved the exceptions.
Moving Forward: Upgrading to JBoss 8.0 Safely
Migrating from JBoss 7.4 to 8.0 involves more than just binary upgrades—it’s also about adapting to the evolving Jakarta EE platform. You’ll encounter numerous smaller yet critical changes, like namespace shifts from javax to jakarta, after Jakarta EE took over from the older Java EE platform.
Be prepared: always review official upgrade documentation carefully (WildFly official updates page helps greatly) and ensure your codebase aligns fully with the targeted runtime.
Final Thoughts & Your Next Steps:
Upgrades rarely come totally free—they require careful analysis and often subtle code changes. Resolving the JNDI lookup issue on JBoss 8.0 isn’t hard once you understand the underlying changes within Jakarta EE 10.
Check your dependencies, transition to Jakarta namespaces, and you’ll rapidly clear this nasty roadblock. Have you faced similar challenges with recent Jakarta EE migrations? Let us know your experiences below!
0 Comments