Skip to main content
This page covers common issues you might encounter when using Compose Hot Reload and their solutions.

​
Setup and configuration

​
Hot Reload not starting

If Compose Hot Reload fails to start, verify the following:
1

Check version requirements

Ensure your project meets the minimum version requirements:
  • Kotlin 2.1.20 or higher
  • Compose compiler 2.1.20 or higher
  • Compose Multiplatform 1.8.2 or higher
2

Verify JetBrains Runtime

Compose Hot Reload requires JetBrains Runtime. Your project must target Java 21 or earlier to be compatible with JetBrains Runtime.
3

Check plugin configuration

Verify that the Compose Hot Reload plugin is properly applied in your build.gradle.kts:
plugins {
    alias(libs.plugins.composeHotReload)
}

​
Changes not being detected

If your file changes are not triggering hot reload:
  1. Verify file system watching is enabled: Gradle File System Watching must be enabled for Compose Hot Reload to detect changes. Check your gradle.properties: 
    org.gradle.vfs.watch=true
  2. Check file system compatibility: If you’re on Windows using a Dev Drive (ReFS), see the known limitations page.
  3. Save your files: Ensure you’re actually saving files. The reload is triggered when files are saved to disk.
  4. Check auto mode: If you’re using explicit mode, you need to manually trigger the reload. Consider using auto mode with --autoReload or --auto flag.

​
JetBrains Runtime issues

​
JetBrains Runtime not found

If Gradle cannot find the JetBrains Runtime:

​
Option 1: Use Foojay Resolver

Add the Foojay resolver to your settings.gradle.kts: 
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

​
Option 2: Enable auto-provisioning

Automatic JetBrains Runtime provisioning is an experimental feature. Please report any issues you encounter.
Enable automatic JetBrains Runtime provisioning: 
compose.reload.jbr.autoProvisioningEnabled=true

​
Option 3: Manual installation

Download and install JetBrains Runtime manually and configure your IDE to use it.

​
Build and compilation

​
Build fails after adding Compose Hot Reload

If your build fails after adding the Compose Hot Reload plugin:
  1. Clean build: Try cleaning your build first: 
    ./gradlew clean build
  2. Check for conflicting plugins: Ensure you don’t have conflicting Compose plugins. If you’re using an Android-only project, see the FAQ.
  3. Verify JVM target: Ensure your project targets Java 21 or earlier: 
    kotlin {
    jvmToolchain(21)
}

​
Compilation errors after hot reload

If you encounter compilation errors that only appear during hot reload:
  1. Restart the application: Some changes require a full restart. This is particularly true for changes to global state.
  2. Check for global state issues: See the global state limitations for more information.

​
Performance issues

​
Slow reload times

If hot reload is taking too long:
  1. Use incremental compilation: Ensure Gradle incremental compilation is enabled: 
    kotlin.incremental=true
  2. Increase Gradle memory: Add to your gradle.properties: 
    org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g
  3. Enable configuration cache: In your gradle.properties: 
    org.gradle.configuration-cache=true
  4. Disable unnecessary dev tools: If you don’t need the dev tools UI, run in headless mode: 
    ./gradlew :app:hotRunJvm -Dcompose.reload.devToolsHeadless=true

​
High memory usage

If you’re experiencing high memory usage:
  1. Adjust Gradle daemon memory: Modify org.gradle.jvmargs in gradle.properties
  2. Restart the Gradle daemon periodically: 
    ./gradlew --stop

​
IDE integration

​
Run button not showing in gutter

If you don’t see the Compose Hot Reload run option in the IDE gutter:
  1. Install Kotlin Multiplatform plugin: Ensure you have the Kotlin Multiplatform IDE plugin installed.
  2. Use minimum IDE version: Use IntelliJ IDEA 2025.2.2 or higher, or Android Studio Otter 2025.2.1 or higher.
  3. Manually create run configuration: If the plugin is not available, manually create a Gradle run configuration with the hot reload tasks.

​
Desktop-only projects

For desktop-only Compose Multiplatform projects, you cannot start the application via the run button in the gutter (CMP-3123). Use Gradle tasks instead.
Run from the command line: 
./gradlew :app:hotRunJvm

​
Debugging

​
Enable debug logging

To get more information about what Compose Hot Reload is doing, enable debug logging: 
./gradlew :app:hotRunJvm --debug
Or set Gradle logging level in gradle.properties: 
org.gradle.logging.level=debug

​
Check orchestration connection

Compose Hot Reload uses an orchestration server to communicate between components. If you’re experiencing connection issues, check the console output for connection-related messages.

​
Getting help

If you’re still experiencing issues:
  1. Check the known limitations page
  2. Search existing issues on GitHub
  3. Report a new issue
  4. Ask in the discussions forum

Build docs developers (and LLMs) love

Get started for freeTalk to us