Troubleshooting

Troubleshooting

This page helps you solve common issues with the Compose for Desktop Wizard and generated projects that occurred so far.

---

Release Notes - Linux Desktop Integration Fix

🐧 Linux .deb Package Desktop Integration (Fixed in Latest Release)

Resolution: Fixed a critical Linux desktop integration issue in Compose for Desktop's packageReleaseDeb task.

Problem Discovered

The official Compose for Desktop packageReleaseDeb task generated .desktop files with missing critical metadata:

• Missing StartupWMClass parameter - Linux window managers couldn't associate running windows with desktop entries
• Name parameter - Apps showed mainClass's name instead of actual app names
• Result: After installing, app's icon was generic "settings wrench" icon instead of proper app icons in dock/taskbar

Root Cause Analysis

# What Compose was generating (broken):
[Desktop Entry]
Name=MainKt
Exec=/opt/packageName/bin/packageName
Icon=/opt/packageName/lib/packageName.png
# Missing: StartupWMClass=ActualMainClassName

# What Linux desktop environments need:
StartupWMClass=MainClassName  # Links window to .desktop entry
Name=Your Actual App Name     # Proper display name in menu and dock

Solution Implemented

Added custom Gradle tasks to post-process .deb packages:

1. addStartupWMClassToDebDynamic - Automatically fixes .desktop files by:

   • Extracting the built .deb package
   • Modifying the desktop entry to include proper StartupWMClass and Name values
   • Rebuilding the package with correct metadata

2. packageDebWithWMClass - One-command release process:

   • Runs packageDeb or packageReleaseDeb
   • Automatically applies desktop integration fixes
   • Interactive task selection

Impact

• ✅ Proper Linux desktop integration - Apps now show correct icons in docks/taskbars
• ✅ Professional appearance - No more generic Ubuntu wrench icons
• ✅ Compliant with FreeDesktop.org standards
• ✅ Automated fix - No manual intervention required

Usage

# For new release builds with proper desktop integration:
./gradlew packageDebWithWMClass

# Or run the fix on existing .deb packages:
./gradlew addStartupWMClassToDebDynamic

---

Generated Project Issues

Gradle Wrapper Permission Issues (Linux/macOS)

Problem: Running ./gradlew results in "Permission denied"

• Solution: Make the Gradle wrapper executable:

chmod +x gradlew

This is a common issue with ZIP files as they don't preserve Unix executable permissions.

Windows MSI Upgrade Issues

Problem: Windows installer doesn't recognize updates and installs alongside old version

• Solution: Generate and set a permanent upgrade UUID:

./gradlew generateUpgradeUuid

Copy the generated UUID and paste it into the upgradeUuid field in your build.gradle.kts only once. This ensures MSI installers recognize updates properly.

ProGuard Build Failures with Kotlin Serialization

Problem: Release builds fail with ClassNotFoundException related to serialization

• Solution: The generated proguard-rules.pro includes comprehensive rules for Kotlin Serialization. If you add custom @Serializable classes, ensure they're included:

# Add to proguard-rules.pro for custom serializable classes:
-keep class yourpackage.YourSerializableClass { *; }
-keep class yourpackage.YourSerializableClass$$serializer { *; }