Documentation

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.

Compose HotSwan Settings

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
    }
}

If you use applicationIdSuffix for debug builds (e.g. .debug), include the suffix in the HotSwan setting.

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:

  1. Go to Settings → Plugins and confirm "Compose HotSwan" is listed and enabled.
  2. Restart the IDE if you just installed or updated the plugin.
  3. 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.

View → Tool Windows → HotSwan

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:

  1. Run ./gradlew clean to remove all build outputs.
  2. In Android Studio, use File → Invalidate Caches → Invalidate and Restart.
  3. 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.

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.