NoClassDefFoundError occurs after running embed-server or jdr.sh alongside an active JBoss EAP 7.x/8.x server

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 7.x
  • 8.x

Issue

• Application error such as NoClassDefFoundError happens on JBoss EAP 7.x/8.x after starting embed-server in JBoss-CLI (or executing $JBOSS_HOME/bin/jdr.sh) beside running server
• Starting embed-server (either directly via JBoss-CLI or indirectly via $JBOSS_HOME/bin/jdr.sh with incorrect connection details) while a JBoss EAP instance is running will delete the active server's tmp/vfs directory. This action removes critical class files, causing application failures with NoClassDefFoundError.
• Your application running on JBoss EAP unexpectedly fails with NoClassDefFoundError after you use the JBoss-CLI embed-server command or run the $JBOSS_HOME/bin/jdr.sh diagnostic script.

Resolution

• This is a a known issue tracked by the following JIRA tickets, which is scheduled to be fixed in future releases:
  • Upstream: This content is not included.WFCORE-7294 - embed-server can delete the same tmp/vfs directory for running server
  • 8.1.z: This content is not included.JBEAP-30550, which will be fixed in EAP 8.1.1
  • 8.0.z: This content is not included.JBEAP-30463, which has been fixed in EAP 8.0.11
  • 7.4.z: This content is not included.JBEAP-30462
• Workaround:
  • Do not run embed-server in JBoss-CLI while another JBoss EAP server is running.
  • When using JDR ($JBOSS_HOME/bin/jdr.sh), specify the correct management IP address with -H (--host) option and the management port with -p (--port) option to ensure it connects to the active server instead of starting a new embedded instance.
  • If this issue occurs, restart the running server to recover.

Root Cause

• By design, JBoss EAP clears the tmp/vfs/ directory upon startup. This behavior also applies to the embed-server.
• If embed-server is started while another JBoss EAP server instance is running, it can delete the same "tmp/vfs" directory that the running server is currently using. This directory contains extracted JARs with application classes and libraries.
• The removal of these files can lead to NoClassDefFoundError if the application attempts to load a class that is no longer present.
• Similarly, JDR ($JBOSS_HOME/bin/jdr.sh) may internally start the embed-server to gather information if it fails to connect to the specified management IP address/port (localhost:9990 by default). An incorrect IP address or port will trigger this behavior, causing it to delete the active server's tmp/vfs/ directory and potentially leading to the same error.

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.