Skip to main content

HotSwap in IntelliJ IDEA

Abhishek Sah
Updated

HotSwap reloads classes that were changed during a debugging session into the running JVM, with no restart and no loss of in-memory state. IntelliJ IDEA's debugger uses the standard JVM Class Redefinition API; third-party agents (DCEVM, HotSwapAgent, JRebel) can extend its reach.

For the underlying mechanism, see Reload modified classes.

When HotSwap helps

  • Adjusting the body of an existing method (logic, constants, log statements) while keeping the debug session alive.
  • Iterating on UI handlers, request handlers, or test logic without losing the in-memory state of the running application.

When HotSwap cannot help

Standard JVM HotSwap is limited to method-body changes. The following always require either a restart or an external agent:

  • Changing a method signature.
  • Adding or removing class members (fields, methods, inner classes).
  • Reloading a method that is currently on the call stack. The new body takes effect only after the application exits that frame; until then, the frame is shown as obsolete in the Frames view.

See the full list in HotSwap limitations. When these limits block the workflow, use Dynamic Code Evolution VM: How to use Dynamic Code Evolution VM (DCEVM) in IntelliJ Java debugger.

Quickstart

  1. Start the application in Debug mode.
  2. Edit a method body. A floating Apply HotSwap button appears above the editor (the Code changed indicator).
  3. Click the button, or use Build | Recompile (Ctrl+Shift+F9), or Run | Debugging Actions | Reload Changed Classes.

If the change is accepted, the status bar shows "HotSwap completed". If nothing was compiled since the last reload, the status bar shows "Loaded classes are up to date. Nothing to reload."

Ways to trigger a reload

Trigger Where Notes
Apply HotSwap floating button Above the editor when code is modified during a debug session Press Esc to hide; new edits bring it back.
Compile and Reload File Editor context menu (single file) Compiles only the current file.
Compile and Reload Modified Files Editor context menu (project scope) Compiles all modified files.
Reload Changed Classes Run | Debugging Actions menu Honors the Build project before reloading classes setting.
Automatic reload after build Any build (manual or auto-make) Governed by Reload classes after compilation. See below.

Settings reference

All four settings live in Settings | Build, Execution, Deployment | Debugger | HotSwap and are per-IDE preferences.

Reload classes after compilation

Controls what happens immediately after a successful compilation while a debug session is attached.

  • Always — Changed classes are reloaded automatically after every successful build, manual or automatic. If Enable 'JVM will hang' warning is on and the JVM is currently suspended, a confirmation dialog appears first.
  • Ask — After a manual build, the Reload Changed Classes dialog appears and reloads only on confirmation. After an automatic (background) build, the dialog is suppressed and the reload is silently skipped for that build.
  • Never — Classes are never reloaded automatically. HotSwap is still available on demand from the floating button, the editor context menu, or Run | Debugging Actions | Reload Changed Classes.

Choosing between them:

  • Always for the fastest hands-off feedback loop.
  • Ask for explicit control after every manual build.
  • Never for pure on-demand reloads, or when an external agent (JRebel, DCEVM + HotSwapAgent) is handling reloads, to avoid double-reloading.

Build project before reloading classes

Determines whether explicit HotSwap actions (Reload Changed Classes, the floating button) run a build first.

  • Enabled — The action runs a build, then reloads any changed classes. The session-selection prompt is skipped for that action; the 'JVM will hang' warning still applies when the JVM is suspended.
  • Disabled — The action reloads only classes that were already compiled. If nothing was rebuilt since the last reload, the status bar shows "Loaded classes are up to date. Nothing to reload."

This option does not affect auto-make or Actions on Save; those follow Reload classes after compilation only.

Enable it to guarantee the latest edits are compiled before being reloaded. Disable if a separate build tool (Gradle, Maven, or Bazel delegated build) is already producing class files.

Enable 'JVM will hang' warning

Shows a confirmation dialog before HotSwap proceeds in a risky state. The exact dialog text:

"JVM is currently suspended. Reloading classes with active third-party JVM agents may cause the JVM to hang."

The dialog appears when all of the following are true:

  1. HotSwap is about to reload without asking. For example, Reload classes after compilation = Always, or the floating button is used and bypasses the prompt.
  2. The debugged JVM is currently suspended (typically paused on a breakpoint).
  3. This setting is on.

Dialog buttons: Perform reload classes, Skip reload classes, plus a Do not show again checkbox that disables the setting.

Keep enabled when running under DCEVM + HotSwapAgent, JRebel, or another third-party JVM agent that intercepts class redefinition. With a plain JVM and no agents, the warning is mostly informational.

Suggest HotSwap in the editor when code is modified

Controls the floating Apply HotSwap button and the in-editor Code changed indicator that appear when code is edited during a debug session.

  • Enabled — The floating button appears above the editor when changes are ready to reload; notifications surface when a reload finishes.
  • Disabled — No floating button. Reloads can still be triggered from the editor context menu, from Run | Debugging Actions, or by the Reload classes after compilation setting.

Common Troubleshooting :

HotSwap doesn't fire after saving in Spring Boot / auto-build projects

The most common cause is Reload classes after compilation = Ask. In Ask mode, automatic background builds (auto-make, Actions on Save, Spring Boot DevTools) silently skip HotSwap to avoid prompt spam; only manual builds trigger the dialog.

  • For hands-off reloads: switch to Always.
  • For on-demand reloads: trigger HotSwap explicitly via the floating button, the editor context menu, or Run | Debugging Actions | Reload Changed Classes.

"Loaded classes are up to date. Nothing to reload."

The compiled class files on disk haven't changed since the last reload.

  • Enable Build project before reloading classes, or
  • Run Build | Recompile (Ctrl+Shift+F9) before invoking the HotSwap action, or
  • If the build is delegated to Gradle, Maven, or Bazel, run that build first.

Method changes are not visible after reload

The modified method is still on the call stack. The new body takes effect only after the application exits that frame. The Frames view marks affected frames as obsolete. Step out until the obsolete frame is gone, or restart the affected operation.

HotSwap silently fails on method-signature change or new field

This is a JVM limitation, not a setting. Use DCEVM + HotSwapAgent for unlimited reload: see How to use Dynamic Code Evolution VM (DCEVM) in IntelliJ Java debugger.

Reload is not happening in a Tomcat / application-server project

Tomcat and other application servers use Update classes and resources or Hot swap classes instead of the plain HotSwap action. See Update applications on application servers. For configuration files specifically, see How to HotSwap Tomcat application configuration files in IDEA?.

Floating "Apply HotSwap" button disappeared

The button hides on Esc and reappears on the next code change. If it is permanently absent, verify that Suggest HotSwap in the editor when code is modified is enabled.

Related articles

Comments

0 comments

Please sign in to leave a comment.