Skip to main content
This page covers known issues and limitations of Compose Hot Reload. These limitations are mainly caused by external factors rather than Compose Hot Reload itself. The list does not cover all possible issues and may be updated.
If you encounter any issues not mentioned here, please report them to us.

​
Window behavior issues

​
Window flickering, jumping, or unusual behavior

Compose Hot Reload supports all main operating systems. However, the dev tooling window snapping itself to the main application’s window can cause unusual behavior (flickering, jumping, etc.) on some window managers.

​
Workarounds

You can try one of the following solutions:
  1. Detached mode: Run the dev tools window in detached mode by setting the -Dcompose.reload.devToolsDetached=true property. This launches the dev tools as a regular window, without snapping to the main application’s window.
  2. Headless mode: Run the dev tools window in headless mode by setting the -Dcompose.reload.devToolsHeadless=true property. This launches the dev tools process but does not show any UI.
  3. Disable dev tools: Disable the dev tools process entirely by setting the -Dcompose.reload.devToolsEnabled=false property. This prevents the dev tools process from starting, which may limit some functionality of Compose Hot Reload.
Original issue: CMP-9674

​
Issues with virtual desktops/workspaces

All major operating systems support some form of virtual desktops/workspaces. However, they do not provide a public API for accessing information about the current desktop of the window nor an API for changing the virtual desktop of the window. This means that Compose Hot Reload cannot reliably detect on which virtual desktop the user window spawns and cannot change the virtual desktop of the dev tools window when necessary. The same happens when you move the main application’s window to another virtual desktop: Compose Hot Reload cannot detect that and move the dev tools window accordingly.

​
Solution

If you use virtual desktops, run the dev tools window in detached mode by setting the -Dcompose.reload.devToolsDetached=true property.
Original issue: #426

​
File system and storage

​
Windows Dev Drive (ReFS) incompatibility

Compose Hot Reload relies on Gradle File System Watching to detect changes in the source files. Unfortunately, Gradle does not currently support ReFS.

​
Solution

Move your project to an NTFS-formatted drive.
Gradle issue: #31634Compose Hot Reload issue: #190

​
Multiple applications

​
Running multiple Compose applications in the same IDE instance

The Kotlin Multiplatform IDE plugin currently supports only a single Compose Hot Reload connection at a time. If you try to simultaneously run multiple Compose applications within the same IDE instance, you may experience unexpected shutdowns. Supporting only a single Compose Hot Reload connection in Kotlin Multiplatform is intentional, as having multiple Compose Hot Reload-related UI elements in the IDE can be overwhelming and confusing.

​
Solution

If you’re running multiple Compose applications simultaneously, run only one of them in hot reload mode. Alternatively, you can run other applications from the command line; then Compose Hot Reload will not automatically connect to the IDE.
Original issue: #408

​
Configuration issues

​
Property compose.application.resources.dir is null

Compose desktop native distribution allows adding arbitrary files to the final distribution, accessing them later via the compose.application.resources.dir system property from the application. However, the Compose Gradle plugin currently sets this property only for the run task. For other tasks, including desktopRun, hotRunDesktop, etc., this property is not set.

​
Workaround

Set this property manually in your build.gradle.kts file: 
tasks.withType<ComposeHotRun>().configureEach {
    systemProperty(
        "compose.application.resources.dir",
        project.layout.buildDirectory.dir("compose/tmp/prepareAppResources").get()
    )
}
Compose Hot Reload issue: #343CMP issue: CMP-8800

​
Global state and ViewModels

​
Exceptions when making changes to global state

Compose Hot Reload aims to support any changes to the source code of the application. Unfortunately, it is not always possible, mainly because of global state. When you make changes to your application’s code, Compose Hot Reload invalidates all the affected Compose code and re-renders the UI to ensure that all the references to the ‘old’ code are cleaned up. However, Compose Hot Reload cannot invalidate the global state of your application (except statics), which means that some changes to it may cause exceptions.

​
Solutions

If changes to the global state cause issues in your application, you have two options:
  1. Restart the application after the changes.
  2. Manually reset the global state by adding hooks via the Compose Hot Reload Runtime API.
Add the following dependency: 
implementation("org.jetbrains.compose.hot-reload:hot-reload-runtime-api:*latest version*")
Then use one of these options: 
if (isHotReloadActive) {
    // Non-composable option
    staticHotReloadScope.invokeAfterHotReload {
        // reset your state here
    }
    // Composable option
    AfterHotReloadEffect {
        // reset your state here
    }
}

​
ViewModel support

One common example of global state is ViewModel classes. View models persist their state through changes in the UI, meaning that any information they store will be persisted as well. If you want to use hot reload with view models, you need to reset their state properly after hot reload. 
if (isHotReloadActive) {
  val viewModelStoreOwner = LocalViewModelStoreOwner.current
  staticHotReloadScope.invokeAfterHotReload {
    viewModelStoreOwner?.viewModelStore?.clear()
  }
}
Original issue: #489

​
Get help

If you encounter any issues not mentioned here, please report them to us. If you have any further questions regarding one of the listed issues, please feel free to ask them in the linked original issue or create a new discussion.

Build docs developers (and LLMs) love

Get started for freeTalk to us