Linux Troubleshooting
AppImage install, paths, Vulkan, plugins, and Linux-specific HueForge fixes.
How do I install / update HueForge on Linux?
HueForge ships as an AppImage (no installer). Requires glibc ≥ 2.35.
- Download the Linux build from your order Download Files page / account portal
- Make it executable if needed
- Some distros want the file named like HueForge_vX.Y.Z.AppImage
See the AppImage README for xcb-cursor / dependency notes if the app won't start on your distro.
Where are my settings, filaments, and logs?
| What | Typical path |
|---|---|
| Data | ~/.local/share/HueForge |
| Logs | ~/.local/share/HueForge/Logs |
| Config / cache (repair) | ~/.config/HueForge*, ~/.cache/HueForge |
There is also a convenience link: ~/Documents/HueForge → ~/.local/share/HueForge.
AppRun / Documents issue: if ~/Documents does not exist when HueForge first sets up, a bad install path can replace Documents itself with a data symlink. The correct layout is a HueForge folder inside Documents linking to ~/.local/share/HueForge — not Documents pointing at the data dir. If your Documents folder looks wrong after first run, fix/remove the bad symlink and recreate ~/Documents/HueForge properly (or ask support).
“dialout” / serial permissions (TD1)
Warnings about dialout (or serial device access) are intentional when using a TD1. Add your user to the appropriate group / fix udev rules for the device — don't treat that warning as a generic HueForge crash.
Help / wiki links won't open (AppImage)
Known Qt-env class of bugs with AppImages. Use a default browser, open URLs manually, and include distro + Wayland/X11 when emailing support.
Crashed or won't start — what should I send?
Include HueForge version, distro, session type, File → Export Log File / logs from ~/.local/share/HueForge/Logs.
Stubborn config issues: quit HueForge and clear ~/.config/HueForge* and ~/.cache/HueForge (you may need to re-set preferences).
Email steve@thehueforge.com.
SpotFix — blank 3D view after exiting
Set File → Settings → Model → Render Backend → Vulkan, click Save and Apply, then restart HueForge when prompted. Use sparingly; 0.9.4.2 should improve persistence. Cannot be used with HugeForge currently.
Vulkan on Linux
Most modern desktop distros already ship with Vulkan support. Use File → Settings → Model → Render Backend → Vulkan → Save and Apply, then restart when prompted.
If switching to Vulkan blanks the entire UI, your system may be missing a Vulkan driver/ICD (not just the loader). Install your distro's packages (often mesa-vulkan-drivers, or your GPU vendor's Vulkan packages), then try again.
How do I install a plugin on Linux?
Linux uses .tgz: Plugin Menu → Install Plugin → select the downloaded .tgz (not zip drag-drop). Clear Plugins under the config dir if reinstalling.
Still stuck?
Email steve@thehueforge.com. Store FAQ.