Help

Help & Troubleshooting

Common fixes for startup issues, crashes, GPU problems, and platform-specific quirks on Windows and Linux. 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.

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

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
Linux ~/.local/share/PaintFE/paintfe_settings.cfg

🪟 Windows

Startup & Launch

Windows shows “Windows protected your PC” when opening PaintFE
This is a Windows SmartScreen warning. It appears for applications that do not yet have a Microsoft‑trusted code signing certificate. PaintFE is safe; code signing is in progress.

How to run it:
  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.

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

🐧 Linux

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.
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, 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 / 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.