PhotoCraft troubleshooting: crashes, install, display

Most PhotoCraft launch failures and crashes come from the graphics (GPU) backend or from a stale settings file. Most display and input glitches on Linux come from Wayland. Start with the quick checks below, then find your symptom. PhotoCraft is early alpha software, and the status shown for each issue is as of 9 October 2026, when v0.5.0 was the latest release.

Quick checks

1. Update. Many problems below are fixed in v0.3.0 or v0.5.0. Download the latest build from the official releases, not from a mirror or a repackaged installer.
2. Try the CPU renderer once. Start PhotoCraft with --safe-gpu to use the CPU renderer for a single launch.
3. Check Help › System Info… It shows the graphics adapter, backend, driver and fallback state, and has a Copy button for bug reports.
4. Reset settings if PhotoCraft crashes at start-up right after an update or after you changed a preference (see Reset settings).

Crashes and GPU problems

How PhotoCraft recovers from GPU crashes

Since v0.3.0, PhotoCraft writes a marker file (gpu-starting.json) before it creates the GPU device. If the previous launch died inside the graphics driver, the next launch automatically moves to a safer backend:

OS	Fallback order
Windows	Vulkan → DX12 → CPU
Linux	Vulkan → GL → CPU
macOS	Metal → CPU

PhotoCraft remembers the backend that worked. You can see or change it in Preferences › Performance › GPU Backend, which also has a Reset GPU Backend button. v0.5.0 added Rendering Mode (Automatic, GPU, or CPU / Compatibility) on the same page. If the GPU canvas fails while you work, PhotoCraft switches to CPU compositing and offers Keep Using CPU or Retry GPU.

To force a backend, set WGPU_BACKEND to vulkan, dx12, metal or gl. It overrides both the preference and the automatic fallback.

Windows: crash at launch on Intel graphics

• Symptom: PhotoCraft closes immediately. Windows Event Viewer shows an access violation (0xc0000005) in igvk64.dll, the Intel Vulkan driver.

• Affected: Intel GPUs on Windows (for example UHD Graphics 630), up to v0.2.0.

• Fix: update to v0.3.0 or later. Intel adapters on Windows now default to DX12, and a crash on one launch makes the next launch fall back by itself. On older builds, start PhotoCraft with the DX12 backend from a Command Prompt in its install folder:

  set WGPU_BACKEND=dx12
  photocraft.exe
  

• Status: #4 is open, waiting for confirmation on the affected hardware. The automatic fallback has been confirmed working in a sister app.

Crash at start-up after updating or changing UI font size

• Symptom: PhotoCraft won't start. From a terminal you see FontFamily::Name("medium") is not bound to any fonts, or Error: Wgpu(CustomNativeAdapterSelectionError("no graphics adapter found")).
• Cause: saving UI font size with any value other than Small makes the next launch panic (#1503). A settings folder kept from an older version can also break start-up (#1461, reported on Arch/EndeavourOS with v0.5.0).
• Workaround: in preferences.json, set "uiFontSize": "small" under interface. Or quit and move the whole settings folder aside (see Reset settings). The reporter of #1461 fixed it by clearing ~/.config/photocraft.
• Status: the font-size panic is fixed on main (after v0.5.0). #1461 is open.

Linux: "no graphics adapter found" after choosing CPU rendering

• Symptom: after you switch Rendering Mode to CPU, the next launch exits with "no graphics adapter found", even after switching back to GPU.
• Affected: reported with v0.5.0 on KDE X11 with NVIDIA's proprietary driver.
• Workaround: delete ~/.config/photocraft/gpu-starting.json.
• Status: #1337, open.

Black window in a virtual machine

• Symptom: only a black window appears. One reporter on VMware sees content only while the window is maximized.
• Affected: v0.5.0 in Windows virtual machines. One reporter says v0.3.0 worked.
• Workaround: maximizing the window helped in #1788. Otherwise none is known yet.
• Status: #1647 and #1788 are open.

Very large documents

Huge canvases can exceed the GPU memory budget. The canvas then falls back to slow CPU drawing, and at extreme sizes the app can stop responding (#1015, open). If PhotoCraft says the layers don't fit the GPU memory budget, raise Memory usage in Preferences › Performance. The budget can go up to a quarter of the computer's memory.

Install and launch

macOS: older Intel Macs

• Symptom: the Dock icon bounces and the app quits. In Terminal, /Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft prints Error: Wgpu(RequestDeviceError(... Device(Lost) ...)), even with --safe-gpu.
• Affected: Intel Macs running a newer macOS through OpenCore Legacy Patcher, for example a Late 2013 iMac and a Haswell iMac, including v0.5.0.
• Cause: PhotoCraft's macOS window needs Metal even in CPU mode, and the maintainers suspect the patched graphics drivers.
• Status: #600 and #1859 are open. No workaround is known.

The macOS DMG is signed and notarized, so Gatekeeper should accept it without extra steps.

Linux: missing-library warning

At start-up, PhotoCraft checks for the libraries the display session needs. It prints could not find these libraries ..., with apt/dnf install commands, and starts anyway. Install the listed packages. On musl distributions such as Alpine the warning can appear even though the libraries are present (#1144, open). If the app works, you can ignore it there.

Linux desktop (Wayland)

Dragging files onto the window does nothing

• Cause: the windowing library PhotoCraft uses has no Wayland drag-and-drop support yet.

• Workaround: use File › Open, or copy the image in your file manager and paste it into PhotoCraft. To drag and drop, run PhotoCraft under XWayland:

  WAYLAND_DISPLAY= photocraft
  WAYLAND_DISPLAY= ./photocraft-0.5.0-linux-x86_64.AppImage
  flatpak run --nosocket=wayland --socket=x11 ai.storyteller.photocraft
  

  On main (after v0.5.0), Preferences › Performance › Linux display server = X11 makes PhotoCraft always start under XWayland.

• Status: #386, open until native support arrives upstream.

Pen tablet: no input or no pressure

• Linux Wayland (#639, closed): the pen did nothing at all on v0.5.0 and earlier. The fix is on main and comes in the next release. When a tablet is attached, PhotoCraft opens through Xwayland so its X11 tablet reader gets pressure, tilt and the eraser end. Set PHOTOCRAFT_NATIVE_WAYLAND=1 to opt out. The Flatpak needs --socket=x11. Until then, one reporter got pen input and pressure working in an X11 session. Native Wayland pressure is tracked in #79 (open).
• Windows (#759, open): pressure works only with Windows Ink turned on in the tablet driver. Users confirmed this on v0.5.0. There is no WinTab option yet.
• macOS (#759): pressure fixes are on main but not yet confirmed on hardware.

Other display and input glitches

Symptom	Status	Workaround
Selecting text (Ctrl+A, Shift+arrows, mouse) deletes it (#1381)	Fixed on main, after v0.5.0	Run with WAYLAND_DISPLAY=
One key press repeats endlessly in text fields (#585)	Fixed in v0.5.0, update
Menus open on top of their own titles (#565)	Fixed in v0.3.0, update
Compositor says "not responding" while a file dialog is open, for example on Hyprland (#574)	Fixed on main, after v0.5.0	Click Wait. The dialog keeps working
Interface too small or too large with fractional scaling (#1072, #843)	Fixed steps 75–300% in v0.5.0. Auto follows the system scale on main	Pick a fixed value in Preferences › Interface › UI scale

macOS display

• Oversaturated colours on an external monitor (#569, closed): with the monitor profile set to auto and two displays, v0.2.0 did not follow the display a window was on. Fixed in v0.5.0, so update. The automatic profile now follows each window's display.

Files

Windows: "cannot save … The system cannot find the file specified (os error 2)"

• Symptom: Save, Save As and Export all fail in folders such as Pictures, with "the original file was not changed".
• Cause and fix: Windows Security's folder protection was blocking PhotoCraft. The reporter fixed it by allowing PhotoCraft access to protected folders in Windows Security (Defender).
• Status: #1311, closed with that workaround.

A related bug where save dialogs added .psd to other formats (photo.webp.psd) is fixed on main by #1178.

Other file issues

Symptom	Status
New document ignores the typed width and height and opens at 1920 × 1080 (#340, #588)	Fixed in v0.3.0, update
Crash when opening large PSDs with artboards (#332)	Fixed in v0.3.0, update
Text in a PSD from Photoshop can't be edited (#1317, open)	Double-click the text with the Type tool (T). Install any missing fonts. Rasterized text, shapes and text inside Smart Objects aren't live text. Several PSD text fixes landed after v0.3.0

Crash recovery

PhotoCraft autosaves documents with unsaved changes every 10 minutes by default. The settings are Autosave, Autosave minutes and Recover on launch in Preferences › File Handling. After a crash, the next launch reopens those documents as unsaved, and the status bar reports how many were recovered. Since v0.3.0, recovery data is kept until you save or close the document, so a second crash loses nothing. The web build has no crash recovery.

Logs, settings and reporting a bug

Settings folder

OS	Folder
Windows	%APPDATA%\Photocraft
macOS	~/Library/Application Support/Photocraft
Linux	~/.config/photocraft (or $XDG_CONFIG_HOME/photocraft)

The PHOTOCRAFT_CONFIG_DIR environment variable, or a portable install's data folder, replaces the default location. The folder holds preferences.json, gpu-starting.json, your brush Presets and the crash Recovery data.

Reset settings safely

Quit PhotoCraft and rename the settings folder (for example to photocraft.old) rather than deleting it. Then start PhotoCraft again. Deleting the folder also removes your presets and any unsaved recovery data.

Logs

• v0.5.0: start PhotoCraft from a terminal and copy what it prints. On macOS run /Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft. On Linux run the AppImage or photocraft from a shell.
• main (next release): the app also writes logs/photocraft.log in the settings folder. The previous two runs are kept as photocraft.1.log and photocraft.2.log, so the log of a crashed run survives the restart.
• On main, setting RUST_LOG=debug before launching adds more detail.

Before filing an issue

• You are on the latest release (check Help › About).
• You searched existing issues, including closed ones.
• You tried --safe-gpu, and a reset settings folder for start-up crashes.
• You have the output of Help › System Info… (Copy button).
• You have the terminal output or log file, and exact steps to reproduce.
• For file problems, you can attach a small sample file.

Then use Help › Report an Issue… (it opens the GitHub issue tracker) and paste everything in. For quick questions, there is also the community Discord. For keyboard problems, the shortcuts guide lists the defaults. For Chinese or Japanese input, see the language guide.