When packaging Java or JavaFX applications for Windows using JDK's jpackage utility, developers often hit a frustrating roadblock: the application icon displays perfectly when installed system-wide in C:\Program Files, but disappears or shows as a generic blank icon when installed in a single user's %LocalAppData% directory via --win-per-user-install.

Understanding Why the Icon Fails to Display in AppData

This issue typically occurs due to a combination of Windows Installer (MSI) caching behavior, WiX shortcut declarations, and icon file formatting when operating in a per-user context. Here are the primary causes:

  • Missing Multi-Resolution Icon Sizes: Windows Explorer relies on multiple image dimensions inside a single .ico file (16x16, 32x32, 48x48, and 256x256 pixels). If your ICO file lacks high-DPI assets or proper multi-size layers, Windows often fails to render it in user-level folders.
  • Windows Installer Icon Caching in HKCU: When installing per-user without administrative privileges, Windows Installer stores icon references differently in the registry (under HKCU rather than HKLM). If WiX shortcuts do not explicitly reference the target executable or correct icon ID, Windows Explorer fails to extract the icon from the user directory.
  • Windows Icon Cache Stale State: Windows aggressively caches application icons. During development iterations, Windows may keep referencing a failed icon lookup attempt even after you fix the installer code.

Step-by-Step Solution

1. Verify and Re-encode Your .ico File

Ensure your .ico file contains all standard Windows icon sizes. A single-resolution PNG renamed to .ico will cause icon extraction failures in per-user installs.

You can generate a compliant ICO file using tools like ImageMagick or free online converters, ensuring the following sizes are included:

  • 16x16
  • 32x32
  • 48x48
  • 64x64
  • 128x128
  • 256x256 (PNG compression enabled)

2. Update Your Custom WiX XML Template

If you are overriding the default WiX configuration using --resource-dir, ensure that the shortcut and Add/Remove Programs (ARP) icon properties are explicitly linked. Update your main.wxs or shortcut configuration to assign the icon directly to the shortcut component.

Make sure your ARPPRODUCTICON property and shortcut definitions in WiX are set up correctly: