help

Help & Troubleshooting

Common fixes for startup issues, crashes, GPU problems, and platform-specific quirks on Windows, Linux, and the unofficial macOS builds. If something isn't covered here, open a GitHub issue.

Finding Crash Logs

PaintFE writes a log file on every launch; the file is overwritten each time the app starts, so it always contains output from the most recent session only. If the app crashes or misbehaves, grab this file before you relaunch.

Windows %APPDATA%\PaintFE\paintfe.log

In File Explorer, paste %APPDATA%\PaintFE into the address bar and press Enter.

Windows Store %LOCALAPPDATA%\Packages\<PaintFE_…>\LocalCache\Roaming\PaintFE\paintfe.log

The Store version stores files in a sandboxed package folder. In File Explorer, navigate to %LOCALAPPDATA%\Packages, find the folder whose name starts with PaintFE, then open LocalCache\Roaming\PaintFE inside it. Alternatively, open PaintFE → Edit → Preferences to see the exact resolved path.

Linux ~/.local/share/PaintFE/paintfe.log

Open a terminal and run cat ~/.local/share/PaintFE/paintfe.log. You can also launch PaintFE from a terminal to see live output: ./paintfe 2>&1 | tee paintfe_output.txt

macOS ~/Library/Application Support/PaintFE/paintfe.log

In Finder, press Shift+Command+G and paste ~/Library/Application Support/PaintFE. From Terminal you can inspect the log with cat ~/Library/Application\ Support/PaintFE/paintfe.log.

Resetting Settings

If PaintFE crashes immediately on startup, a corrupted settings file is the most common culprit. Deleting it lets the app rebuild defaults on next launch. This resets keybinds, theme, and UI preferences. Your project files are not affected.

Windows %APPDATA%\PaintFE\paintfe_settings.cfg
Windows Store %LOCALAPPDATA%\Packages\<PaintFE_…>\LocalCache\Roaming\PaintFE\paintfe_settings.cfg

Navigate to %LOCALAPPDATA%\Packages in File Explorer, open the folder whose name starts with PaintFE, then navigate to LocalCache\Roaming\PaintFE.

Linux ~/.local/share/PaintFE/paintfe_settings.cfg
macOS ~/Library/Application Support/PaintFE/paintfe_settings.cfg

WIN

Startup & Launch

Windows shows “Windows protected your PC” when opening PaintFE
This is a Windows SmartScreen warning. It appears for the portable .exe and .zip downloads because they do not yet have a Microsoft‑trusted code signing certificate. PaintFE is safe; code signing is in progress.

Easiest fix: Install from the Microsoft Store instead. Store apps are verified by Microsoft and will never trigger SmartScreen warnings. You also get automatic updates.

If using the portable download:
  1. Click More info on the SmartScreen dialog.
  2. Click Run anyway.
  3. You will only need to do this once per release.

If you prefer to verify before running: the source code is public on GitHub. You can build the binary yourself with cargo build --release and the SmartScreen warning will not appear for self‑compiled binaries.
App opens then immediately closes, or shows a brief black window
This almost always means the app crashed before the window could render. Check the log file at %APPDATA%\PaintFE\paintfe.log; the last few lines will say what failed. The most common causes are an outdated GPU driver or a corrupted settings file. Try resetting settings first.
Error: "no suitable adapter found" or similar wgpu message at startup
PaintFE requires DirectX 12 (wgpu DX12 backend) or Vulkan. Update your GPU drivers from the manufacturer:
• NVIDIA: GeForce Experience or nvidia.com/drivers
• AMD: AMD Software: Adrenalin or amd.com/support
• Intel: Intel Driver & Support Assistant
Also verify your Windows version is at least Windows 10 v1903.
App launches but shows a "software renderer" warning
PaintFE fell back to CPU-based rendering because no compatible GPU was found. The app is fully functional but will be slower on large canvases. Updating GPU drivers usually resolves this. If you're on a VM, GPU passthrough is required for hardware acceleration.

GPU & Graphics

Canvas appears black, flickering, or renders incorrectly
This is typically a driver bug. First try updating your GPU drivers. If the issue persists, try right-clicking the PaintFE .exe → Properties → Compatibility tab → "Override high DPI scaling behavior" and set it to "Application". Some NVIDIA users also need to disable "Threaded Optimization" in the NVIDIA Control Panel for PaintFE.
UI is extremely small / doesn't scale on a 4K / HiDPI display
Windows may be overriding the app's DPI awareness. Right-click the .exe → Properties → Compatibility → "Change high DPI settings" → enable "High DPI scaling override" and set it to "System (Enhanced)".
GPU acceleration is active but performance feels slow at 4K
Check that PaintFE is running on your dedicated GPU, not the integrated one. In Windows Settings → System → Display → Graphics, add PaintFE and set it to "High performance". On laptops with NVIDIA Optimus, you can also right-click the .exe and choose "Run with graphics processor → High-performance NVIDIA processor".

Crashes & Freezes

App crashes when opening a specific file
Launch PaintFE normally, then use File → Open to load the file. Check the log at %APPDATA%\PaintFE\paintfe.log for the error. If it's a RAW camera format, try converting to TIFF or PNG first using another tool; not all RAW variants are supported.
App crashes or hangs when applying a filter on a large canvas
Some filters (Median, Oil Painting, Crystallize) are CPU-intensive at large radii. This is expected on very large canvases. If it crashes rather than just being slow, check the log; the GPU may have run out of VRAM. Try reducing canvas size or closing other GPU-heavy applications.
Windows crash report / app stopped responding
Windows stores crash dumps in %LOCALAPPDATA%\CrashDumps (if configured) and in Event Viewer → Windows Logs → Application. Open Event Viewer, filter by "Error", find the PaintFE entry, and include the "Faulting module" and "Exception code" in your bug report. The PaintFE log at %APPDATA%\PaintFE\paintfe.log will also contain the panic message if Rust caught it.

Microsoft Store Version

What is the difference between the Store version and the portable download?
They are the same application built from the same source code. The Microsoft Store version is packaged as an MSIX and is verified by Microsoft. Key differences:

Store version: automatic updates, no SmartScreen warnings, clean install/uninstall via Windows, sandboxed settings storage.
Portable version: single .exe you can run from anywhere (USB drive, network share), no installation needed, settings stored in %APPDATA%\PaintFE.

Feature-wise, both versions are identical. Choose whichever fits your workflow.
Settings or log file location is different in the Store version
The Microsoft Store version runs in a lightweight app container. Your settings and log files are stored in a sandboxed location instead of the standard %APPDATA%\PaintFE path.

To find them, open File Explorer and navigate to:
%LOCALAPPDATA%\Packages and look for the folder starting with PaintFE. Inside it, your data will be under LocalCache\Roaming\PaintFE.

Alternatively, just open PaintFE and go to Edit → Preferences — the settings file and log file paths are shown there.
How do I update the Store version?
The Microsoft Store handles updates automatically. You can also check manually: open the Microsoft Store app → Library (bottom left) → Get updates.
CLI / headless batch mode doesn't work from the Store version
The Store (MSIX) version may not be directly accessible as paintfe.exe from the command line because Windows Store apps use a virtualized filesystem.

For CLI/batch processing use cases, download the portable .exe from the download page or latest GitHub release instead.

Other Issues

Antivirus flags or quarantines PaintFE
Some antivirus tools flag new Rust binaries via heuristic scanning. PaintFE contains no network code and no obfuscation — you can verify this by building from source. This is a false positive. Add the PaintFE folder to your AV exclusion list, or submit the file to your AV vendor's false‑positive portal to get it whitelisted. The binary will also be submitted to VirusTotal before each release.

Tip: The Microsoft Store version is verified by Microsoft and is less likely to be flagged by antivirus software.
Keybinds aren't working as expected
All keybinds are customizable via Edit → Preferences → Keybinds. If a shortcut seems completely unresponsive, check that the canvas panel has focus (click on it once). Some tools also only accept input when the cursor is over the canvas area.

LNX

Startup & Launch

Running the binary does nothing / no window appears
First make sure the binary is executable: chmod +x ./paintfe

Launch from a terminal to see output: ./paintfe 2>&1
Any error message will appear in the terminal and is the first thing to include in a bug report.
App crashes immediately with "no suitable wgpu adapter"
PaintFE requires Vulkan. Install the Vulkan runtime for your distro:
• Ubuntu/Debian: sudo apt install libvulkan1 mesa-vulkan-drivers
• Fedora: sudo dnf install vulkan-loader mesa-vulkan-drivers
• Arch: sudo pacman -S vulkan-icd-loader mesa vulkan-radeon (or vulkan-intel / nvidia-utils)

Verify Vulkan is working: vulkaninfo | head -20
Crashes on startup after an update
Try resetting the settings file at ~/.local/share/PaintFE/paintfe_settings.cfg. The settings format can change between versions and an old file may contain values the new version can't parse.

Vulkan & GPU

Vulkan is installed but PaintFE still falls back to software rendering
Check which Vulkan ICD is active: vulkaninfo 2>&1 | grep deviceName
If it shows "llvmpipe" or "softpipe", your hardware Vulkan driver isn't loading. For NVIDIA: ensure nvidia-utils and vulkan-icd-loader are installed and the NVIDIA driver version matches your kernel module. For AMD: ensure vulkan-radeon (RADV) or amdvlk is installed.
NVIDIA: canvas corruption or GPU crash (TDR)
Some older proprietary NVIDIA drivers have Vulkan issues. Try the latest driver from your distro's repository or from nvidia.com. If you're on the open-source nouveau driver, switch to the proprietary driver; Vulkan support in nouveau is experimental.
Want to force software rendering for testing
Set WGPU_BACKEND=gl before launching: WGPU_BACKEND=gl ./paintfe
This forces the OpenGL (GLES) backend. Performance will be lower but it can help isolate whether a bug is Vulkan-specific.

Wayland / X11

App crashes or shows a black window on Wayland (GNOME / KDE)
Try forcing X11 (XWayland) mode:
WINIT_UNIX_BACKEND=x11 ./paintfe

If that works, the issue is Wayland-specific. You can make this permanent by wrapping it in a launch script or desktop entry.
Window appears but input (mouse / keyboard) doesn't work on Wayland
Some Wayland compositors have input issues with wgpu/winit apps. Try:
1. Force X11: WINIT_UNIX_BACKEND=x11 ./paintfe
2. On KDE Plasma, disable "Pointer Acceleration" in System Settings → Input Devices → Mouse
3. Check if your compositor supports xdg-shell (all modern compositors do)
HiDPI / scaling is wrong on Wayland
Set the scale manually: WINIT_X11_SCALE_FACTOR=2 ./paintfe (replace 2 with your display's scale factor, e.g. 1.5). On Wayland you can also try GDK_SCALE=2 ./paintfe.

Other Issues

Text tool shows no fonts or very few fonts
PaintFE uses the system font cache. Rebuild it: fc-cache -fv
Make sure you have fonts installed: fc-list | wc -l should return more than a handful. On minimal installs, install a font package like fonts-dejavu (Debian) or dejavu-fonts (Fedora/Arch).
Clipboard paste (Ctrl+V) doesn't work from other apps
On Wayland, clipboard access from other apps requires both apps to use the same clipboard protocol. Try on X11/XWayland (WINIT_UNIX_BACKEND=x11 ./paintfe) where clipboard interop is more reliable. On X11, ensure xclip or xsel is installed.
AI background removal fails to load ONNX Runtime
PaintFE dynamically loads the ONNX Runtime shared library. On Linux, download libonnxruntime.so from the ONNX Runtime releases page and set the path in Edit → Preferences → AI. Make sure the .so is accessible and not blocked by SELinux/apparmor.

MAC

Startup & Launch

macOS says PaintFE cannot be opened because the developer cannot be verified
The GitHub macOS builds are unsigned and unnotarized. That means Gatekeeper will warn on first launch.

Recommended flow:
  1. Download the correct build from the download page: arm64 for Apple Silicon, x86_64 for Intel Macs.
  2. Open the .dmg and copy PaintFE somewhere outside the mounted image, such as ~/Applications.
  3. Control-click or right-click PaintFE, then choose Open.
  4. If macOS still blocks it, open System Settings → Privacy & Security and click Open Anyway.

If you prefer Terminal, remove the quarantine flag manually with xattr -dr com.apple.quarantine /path/to/PaintFE.
The app does nothing when double-clicked
Launch it from Terminal first so you can see any immediate error output: /path/to/PaintFE 2>&1 | tee ~/paintfe_output.txt

Also check ~/Library/Application Support/PaintFE/paintfe.log. If there is no log at all, Gatekeeper usually blocked the binary before the app started.
I downloaded the wrong architecture
Apple Silicon Macs should use the arm64 build. Intel Macs should use the x86_64 build. If you intentionally run the Intel build on Apple Silicon, install Rosetta first: softwareupdate --install-rosetta --agree-to-license.

Metal & Graphics

The window opens but the canvas is black, corrupt, or obviously rendering wrong
The macOS builds use wgpu's Metal backend. Because these builds are not yet an officially supported release target, graphics bugs should be treated as platform-specific regressions.

First, make sure you are on the correct architecture build and on a current macOS release. Then relaunch from Terminal, collect paintfe.log, and report the issue with your Mac model, macOS version, and whether the failure reproduces on both the arm64 and x86_64 builds.
Performance is unexpectedly slow on Apple Silicon
Confirm you are using the native arm64 build. Running the Intel build under Rosetta is useful for comparison, but it is not the fastest path. If the native build is still slow, include the canvas size and the exact tool or filter that triggered the slowdown in your bug report.

Other Issues

How supported is macOS right now?
macOS builds are produced automatically by GitHub Actions for convenience, but they are still unofficial. Windows and Linux remain the primary tested platforms.

If you hit a macOS-only issue, please include the log file, exact build used, Mac model, and macOS version when you open an issue.
Where are my settings and autosaves on macOS?
Settings and logs live in ~/Library/Application Support/PaintFE/. Autosaves are stored in the autosave folder inside the same directory.
bug reports

What to Include

A good bug report gets a fix fast. A vague one sits in the backlog. Include as much of the following as you can:

  • OS + version: e.g. Windows 11 23H2, Ubuntu 24.04, macOS 15.3, Arch Linux (rolling)
  • GPU + driver version: e.g. NVIDIA RTX 3070 driver 555.58, AMD RX 6700 driver 24.5.1
  • PaintFE version: shown in the title bar or Help > About
  • Steps to reproduce: what exactly causes the issue, step by step
  • Expected vs actual behavior: what you expected to happen, and what happened instead
  • Log file: the full contents of paintfe.log (see Finding Crash Logs)
  • Screenshot: if the issue is visual, attach one
  • Sample file: if it only happens with a specific file, attach it (or a small crop that reproduces the issue)

Report Template

Copy and paste this into your GitHub issue:

**OS:** Windows 11 23H2 / macOS 15.3 / Ubuntu 24.04 / ... **GPU + driver:** NVIDIA RTX 3070, driver 555.58 **PaintFE version:** v1.0.0 **Steps to reproduce:** 1. Open PaintFE 2. Load a large TIFF file 3. Apply Filter > Blur > Gaussian Blur with radius 50 4. App crashes **Expected:** Blur applies successfully **Actual:** App closes without error dialog **Log file contents:** ``` [paste contents of paintfe.log here] ```

Opening an Issue

Bug reports and feature requests go on GitHub Issues. Please search existing issues first to avoid duplicates.

Open a Bug Report Browse Existing Issues →
A note on crash reports: Because PaintFE is fully offline, there is no automatic crash reporting. Bugs only get fixed if they're reported. If something goes wrong, checking the log file and opening an issue takes about five minutes and makes the app better for everyone.