Debugging with Wildfly and Byteman


I was trying to start a debugger in Intellji with JBoss Wildfly and Byteman

Byteman requires to specify the jars and config via JAVA_OPTS which was added in wildfly standalone.conf.bat

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:C:/test/byteman-download-4.0.13/lib/byteman.jar=script:c:/test/test.btm,sys:C:/test/byteman-download-4.0.13/lib/byteman.jar -Dorg.jboss.byteman.transform.all=true -Dorg.jboss.byteman.verbose -Dorg.jboss.byteman.debug"

Intellji can start up Wildfly without issue in Run mode. But when it was started in debug mode, it gives the following error.


Exception in thread "main" java.lang.NoClassDefFoundError: org/jboss/byteman/rule/exception/EarlyReturnException
at java.lang.Class.forName0(Native Method)
at java.lang.Class.forName(
at org.jboss.modules.Main.main(
Caused by: java.lang.ClassNotFoundException: org.jboss.byteman.rule.exception.EarlyReturnException from [Module "" version 10.0.3.Final from local module loader @1caa0244 (finder: local module finder @7ce026d3 (roots: C:\jboss\wildfly-18.0.1.Final\modules,C:\jboss\wildfly-18.0.1.Final\modules\system\layers\base))]
at org.jboss.modules.ModuleClassLoader.findClass(
at org.jboss.modules.ConcurrentClassLoader.performLoadClassUnchecked(
at org.jboss.modules.ConcurrentClassLoader.performLoadClass(
at org.jboss.modules.ConcurrentClassLoader.loadClass(

In the Debug startup tab, there is a JAVA_OPTS predefined and not modifiable. I think it is then reason causing this error.

Official comment


I believe that the important part of the workaround is either

- to explicitly add `-Djboss.modules.system.pkgs=org.jboss.byteman` into the VM Options field in the Server tab of JBoss run configuration

- or, alternatively, to change the conditional logic in the standalone.conf which only sets `-Djboss.modules.system.pkgs` in case if JAVA_OPTS is not passed


if [ "x$JAVA_OPTS" = "x" ]; then

   JAVA_OPTS="-Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m"

   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"


   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"



Hope that helps, 


Could you please share standalone.conf.bat and the full command line output from the Run console? The files can be uploaded at


I uploaded the files. Please check


Unfortunately, we can't check the files until you provide the upload ID.


Upload ID: 2020_12_03_NiyAqZwFLBxMEQ3J (files: standalone.conf.bat, run.txt) 



It looks like the output provided is from Run when it's working fine. Can you provide the output from Debug when it fails?

The server should still use the options you set in standalone.conf.bat, so it's not clear why it fails.


Please check this one out, Upload ID: 2020_12_03_Y6NWvKeUt6nwC6r9 


The output indicates all the the options are specified correctly and Byteman even performs some actions before failing.

 JAVA_OPTS: " -agentlib:jdwp=transport=dt_socket,address=,suspend=y,server=n -javaagent:C:\Users\xxx\AppData\Local\JetBrains\IntelliJIdea2020.3\captureAgent\debugger-agent.jar -javaagent:C:/test/byteman-download-4.0.13/lib/byteman.jar=script:c:/test/jdbcleak.btm,sys:C:/test/byteman-download-4.0.13/lib/byteman.jar -Dorg.jboss.byteman.transform.all=true -Dorg.jboss.byteman.verbose -Dorg.jboss.byteman.debug "

It could be that Byteman is somehow incompatible with the debugger agent used at the same time. I would contact Byteman support for help.


Unfortunately, Byteman is lacking of support


You can try adding byteman.jar as a module for your WildFly installation which may help with the ClassNotFoundException. .


It does not work even I specified to load the module globally in standalone.xml

<module name="com.byteman" slot="main" />

I think the byteman is loaded before Wildfly is loading its modules


Our engineers made it work with the following changes:

JAVA_OPTS="$JAVA_OPTS -javaagent:/tmp/byteman/byteman.jar=boot:/tmp/byteman/byteman.jar,boot:/tmp/byteman/byteman-sample.jar,listener:true"

(boot instead of sys, no script, add listener:true , without additional-D... ). Change the paths according to your system.

In Run Configuration VM Options:

-Dorg.jboss.byteman.transform.all=true -Dorg.jboss.byteman.verbose -Dorg.jboss.byteman.debug -Djboss.modules.system.pkgs=org.jboss.byteman

This way both Run and Debug work correctly.

Rules can be added from the terminal:

bash-3.2$ ./ 
no rules installedbash-3.2$ ./ -b /tmp/byteman/byteman-sample.jar
append boot jar /tmp/byteman/byteman-sample.jarbash-3.2$ ./ /tmp/byteman/PeriodicStats.btm
install rule set period
install rule dump stats
install rule count thread create
install rule count thread start
install rule count thread run
install rule count thread exit
install rule count file open read File
install rule count file open read File Descriptor
install rule count file open write File
install rule count file open write File Descriptor
install rule count file input stream close
install rule count file output stream close
install rule count class loadsbash-3.2$ ./
# File /tmp/byteman/PeriodicStats.btm line 156
... rest output omitted

Please sign in to leave a comment.