Troubleshooting

This page covers the most common issues you may encounter while using Compose HotSwan, along with their causes and solutions. Each section includes the error message or symptom, what triggers it, and step-by-step instructions to resolve it.

Module Not Found

HotSwan cannot locate the Gradle module specified in the plugin settings.

Cause: The module path configured in the HotSwan settings does not match an actual Gradle module in your project. This is especially common in Kotlin Multiplatform (KMP) projects where the Android target is nested under a submodule.

Solution: Open Settings → Tools → Compose HotSwan and update the module path. For standard single-module projects, the default :app works. For KMP projects, use the full path to the Android target:

Single module: :app
KMP project: :app:androidApp or :composeApp
Multi-module: :feature:home (the module containing the code you are editing)

You can verify your module path by checking settings.gradle.kts for the include() declarations.

App Launch Failed

HotSwan fails to launch the app because the package name does not match.

Cause: The App Package Name in HotSwan settings differs from the applicationId declared in your module's build.gradle.kts. This can happen when you have different applicationId values for debug and release variants, or when namespace and applicationId differ.

Solution: Open Settings → Tools → Compose HotSwan and set the App Package Name to match the exact applicationId of the build variant you are running. Check your Gradle file:

android {
    namespace = "com.example.app"       // ← not this
    defaultConfig {
        applicationId = "com.example.app" // ← use this value
    }
    buildTypes {
        debug {
            applicationIdSuffix = ".debug" // ← include this if present
        }
    }
}

If your debug build type uses applicationIdSuffix (e.g. .debug), the full package name becomes com.example.app.debug. Make sure the HotSwan setting includes this suffix.

If you are unsure of the exact package name, run the following command to see installed packages on the device:

adb shell pm list packages | grep yourapp

Tool Window Not Visible

The HotSwan tool window does not appear in the IDE.

Cause: The plugin is either not installed, not enabled, or the IDE needs a restart to register the tool window.

Solution:

Go to Settings → Plugins and confirm "Compose HotSwan" is listed and enabled.
Restart the IDE if you just installed or updated the plugin.
After restart, go to View → Tool Windows → HotSwan to open the panel.

If the tool window still does not appear, check the IDE's Help → Show Log in Explorer/Finder for plugin loading errors.

Version Mismatch

The IDE plugin version and Gradle plugin version are out of sync.

Cause: The HotSwan IDE plugin and the Gradle plugin communicate through a shared protocol. When their versions diverge, protocol messages may be incompatible, causing silent failures or unexpected behavior.

How to check:

IDE plugin version: Settings → Plugins → Compose HotSwan — the version is displayed next to the plugin name.
Gradle plugin version: Check your build.gradle.kts or version catalog for the hotswan dependency version.

Solution: Update both plugins to the same latest version. After updating the Gradle plugin, run a Gradle sync. After updating the IDE plugin, restart the IDE.

Why is my app fully re-run instead of hot reloaded?

HotSwan triggers a full incremental build and reinstall instead of a hot reload.

Cause: Your code change involves a structural modification that the Android Runtime cannot apply in-place. Examples include adding or removing functions, changing data class properties, modifying constructors, or altering the class hierarchy. HotSwan detects these cases during the pre-check and automatically falls back to a full build to keep the app stable.

See the Limitations page for the complete list of changes that cannot be hot reloaded and why each one requires a full build.

What to check:

HotSwan console: The tool window shows whether the change was hot reloaded or fell back to a full build, along with the reason.
Scope your edit: If you only changed a composable body or function body, it should hot reload. If you also touched a constructor, added a parameter, or changed a class signature, the fallback is expected.
Lambda renumbering: Adding or removing lambdas in the middle of a file can cause internal class renumbering, which also triggers a full build.

This is by design — HotSwan prioritizes app stability over speed. When a structural change is detected, a full build is the safest path. The fallback is fully automatic and you do not need to take any manual action.

Device Not Detected

HotSwan does not detect a connected device or emulator.

Cause: HotSwan uses ADB to communicate with devices. If ADB is not available, the device is not authorized, or USB/wireless debugging is not enabled, the connection will fail.

Solution:

USB debugging: Enable Developer Options → USB Debugging on the device. Accept the authorization dialog when prompted.
ADB path: Ensure adb is accessible from your terminal. Android Studio typically bundles ADB at $ANDROID_HOME/platform-tools/adb.
Wireless debugging: For wireless connections, the device and computer must be on the same network. Use adb pair followed by adb connect to establish the connection.
Verify connection: Run adb devices in your terminal. The device should appear as device (not unauthorized or offline).

Slow First Reload

The first hot reload after opening a project takes significantly longer than subsequent reloads.

Cause: The first reload requires a cold compilation pass. HotSwan's compiler plugin needs to build the initial baseline of class structures and set up incremental compilation caches. This is a one-time cost per session.

Expected timings:

First reload: 3–8 seconds depending on module size and machine performance.
Subsequent reloads: Under 1–2 seconds for typical composable body changes.

Incremental compilation kicks in after the first reload. Only the changed functions are recompiled, making subsequent reloads much faster. If reloads remain slow after the first one, check that your Gradle daemon has sufficient memory allocated.

Changes Not Detected

You save a file but HotSwan does not trigger a reload.

Cause: HotSwan relies on the IDE's virtual file system (VFS) to detect file changes. If you edit files with an external tool (terminal editor, CLI script, AI coding agent), the IDE may not be aware of the change until it refreshes its VFS.

Solution:

External edits: If you edit files outside the IDE, the VFS will refresh automatically within a few seconds. You can also manually trigger a refresh with File → Reload All from Disk or the keyboard shortcut.
File outside source set: HotSwan only watches files within the configured module's source sets. If your file is outside src/main/java or src/main/kotlin, it will not be detected.
Auto-save disabled: If IDE auto-save is disabled, ensure you manually save the file (Ctrl+S / Cmd+S) before expecting a reload.

Build Errors After Plugin Update

Build fails after updating the HotSwan Gradle plugin to a newer version.

Cause: Stale Gradle caches or compilation outputs from the previous plugin version can conflict with the updated plugin. The compiler plugin generates metadata that is version-specific, and old cached metadata may be incompatible.

Solution: Invalidate caches and perform a clean build:

Run ./gradlew clean to remove all build outputs.
In Android Studio, use File → Invalidate Caches → Invalidate and Restart.
After the IDE restarts, run a full Gradle sync and build.

If the error persists after a clean build, check the error message for specific version requirements. Some HotSwan updates may require a minimum Kotlin or AGP version. Refer to the release notes for compatibility details.

No Merged DEX Dirs Found (Kotlin Multiplatform Project)

HotSwan cannot locate the compiled DEX output for the configured module.

Cause: The module path in HotSwan settings does not match your actual project structure. This is especially common in Kotlin Multiplatform (KMP) projects where the Android target is a nested submodule, or in multi-module projects where the default :app does not point to the correct module.

Solution: Open Settings → Tools → Compose HotSwan and update the module path to match your project layout:

Standard project: :app
KMP project: :app:androidApp or :composeApp

You can verify the correct module path by checking settings.gradle.kts for the include() declarations. After updating the path, stop and restart the HotSwan session.

Broken Pipe (SocketException)

HotSwan fails to connect to the app on the device with a SocketException: Broken pipe error.

Cause: The app does not have the INTERNET permission, which is required for the socket connection between the IDE plugin and the on-device client library.

Solution: Add the INTERNET permission to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Most apps already have this permission for network calls. If your app runs without network access, this may be the only missing piece. After adding the permission, rebuild and run the app before starting a HotSwan session.

java.lang.System::load Warning

A warning about java.lang.System::load appears in the Gradle output during hot reload.

Cause: This is a JDK 17+ reflective access warning emitted by Gradle's internal native library loader. It is not related to HotSwan and does not affect hot reload functionality.

Solution: This warning can be safely ignored. It does not indicate any problem with your project or the HotSwan plugin. Gradle is expected to resolve this in a future version.

Auto Reload Not Working (Live Edit Setting)

HotSwan detects file changes but does not automatically trigger a hot reload on save. You have to manually click the refresh button.

Cause: HotSwan relies on Android Studio's Live Edit setting to detect file saves. If Live Edit is set to None, the IDE does not notify plugins when files are saved, so HotSwan cannot detect your changes automatically.

Solution: Open Settings → Editor → Live Edit and select one of the following options:

Push Edits Automatically (recommended): HotSwan triggers on every file change.
Push Edits Manually on Save: HotSwan triggers when you press Cmd+S / Ctrl+S.

Make sure the Live Edit checkbox at the top is also enabled.

Still stuck?

If none of the solutions above resolve your issue, open a report on the Issue Tracker. Include the HotSwan plugin version, your IDE and Kotlin versions, and any relevant logs from the HotSwan tool window.