Troubleshooting

If the workflow does not behave as expected, check the following before restarting the application:

  1. Check the compile result. If the compile fails, JRebel has nothing to reload. Fix the compilation problem, recompile, wait briefly, and verify the change again.

  2. Wait a few seconds before verifying. JRebel needs time to detect filesystem changes and apply the changes to the running application. Wait a few seconds before verifying changes.

  3. Verify that JRebel is attached. JRebel should normally be attached with -agentpath and the platform-specific native library. Use -javaagent only when -agentpath is not available for the target platform and you have completed the required bootstrap flow. If using -javaagent, the initial bootstrap run must finish before JRebel can reload changes. If the JRebel startup banner appears when the application starts, JRebel is attached. The banner also indicates whether licensing succeeded.

  4. Verify the running application. Verify the change against the running application, rather than letting the agent assume that it worked because the files changed on disk. Use an HTTP request, log output, or another runtime check appropriate for the change.

  5. Check the license. JRebel requires a valid license to reload changes. If the license file is missing, the license server is unreachable, or licensing fails, correct the licensing problem before relying on hot reload.

Common agent failure modes

  • Restarting the application after each change

  • Packaging or rebuilding instead of compiling incrementally

  • Checking too soon after compilation

  • Adding code workarounds instead of correcting the JRebel configuration

When to restart