PhotoCraft Troubleshooting — Fix Startup, Display, File & Automation Problems

Encountering a bug in early alpha? Fixes below are organized by symptom and verified against PhotoCraft v0.2.0 ~ v0.3.0. If filing an issue on GitHub Issues, always include: OS version + Document Dimensions + Layer Count + Screenshot.

---

1. Installation & Startup Errors#

ERR-INST-001 — Windows Installer Hangs / Freezes#

• Symptom: Running the Windows installer displays "Please wait while Windows configures PhotoCraft", but the progress bar completes and nothing launches.
• Root Cause: Upstream installer packaging bug on 64-bit Windows (GitHub Issue #866).
• Solution:
  1. Do not re-run the installer.
  2. Go to the official Releases page and download the Portable ZIP version (e.g., photocraft-v0.3.0-windows-x86_64-portable.zip).
  3. Extract to any folder and run photocraft.exe directly.

ERR-INST-002 — Linux: Double-Click Fails / Missing Shared Libraries#

• Symptom: Application fails to launch silently or prints errors like cannot open shared object file: libxkbcommon.so.
• Solution:
  • Quickest Fix: Use the Flatpak (flatpak run ai.storyteller.photocraft) or AppImage, which package all runtime dependencies.
  • System Packages: If building or using tarball on Ubuntu/Debian, run:

    sudo apt install libxkbcommon-x11-0 libwayland-client0 libwayland-cursor0 libxcursor1 libxrandr2 libxi6
    

  • Note: v0.3.0+ builds include an automated runtime self-check (#201) with explicit terminal messages.

macOS: "Cannot be opened because Apple cannot check it for malicious software"#

• Symptom: macOS Gatekeeper blocks opening the newly downloaded application.
• Solution: Right-click the app in /Applications → select Open → click Open in the confirmation dialog. (PhotoCraft is Developer-ID signed and Apple-notarized, but newly distributed binaries require initial manual confirmation).

macOS: CLI Terminal Hangs on First Run#

• Symptom: Running photocraft CLI halts indefinitely on the initial launch.
• Cause: macOS is performing an online notarization check. Keep internet connected for ~15 seconds until verification finishes. You can confirm validity via:

  spctl --assess --type install -vv /Applications/PhotoCraft.app
  

---

2. Display, Canvas & GPU Glitches#

ERR-GPU-001 — Black Canvas, Flickering, or GPU Device Loss Crashes#

• Symptom: The workspace canvas remains black, or the app logs a crash indicating wgpu::DeviceLost or GPU timeout.
• Solution:
  1. Update GPU Drivers: PhotoCraft relies on hardware Vulkan/DirectX12/Metal. Update to the latest official NVIDIA, AMD, or Intel graphics drivers.
  2. Upgrade to v0.3.0: v0.3.0 incorporates crash-safe startup and automatic device-loss fallback (#4, #243, #252).
  3. Multi-GPU Laptops: Force PhotoCraft to use the dedicated discrete GPU in Windows Settings → Graphics Settings.

ERR-GPU-002 — 16-bit / 32-bit Floating-Point Documents Render Inaccurately#

• Cause: Some GPUs lack Rgba32Float render targets.
• Solution: Upgrade to v0.2.0+. PhotoCraft now automatically degrades texture pipelines to Rgba16Float without loss of visual precision.

UI Display: CJK Text or Panels Show Hollow Boxes (Tofu)#

• Cause: System is missing CJK (Chinese/Japanese/Korean) fallback fonts.
• Solution: Install standard system CJK font packs (e.g. fonts-noto-cjk on Linux). Official binary releases bundle standard localized fonts.

---

3. PSD & Document Opening Issues#

Specific PSD File Fails to Open or Shows Misaligned Layers#

• Cause: The PSD file contains proprietary Adobe features not yet implemented in the clean-room engine.
• Solution:
  • In Photoshop, ensure the document was saved with "Maximize Compatibility" turned ON.
  • Please report the file details on the GitHub Issue Tracker using the standard template.
  • Archival Note: When saving PSDs in PhotoCraft, unmodeled blocks are safely retained, but files are not byte-identical. Do not overwrite your original master PSDs.

Nikon Compressed NEF Opens as Low-Resolution Preview#

• Cause: Decoding proprietary Nikon compressed RAW formats is temporarily constrained under clean-room development rules.
• Workaround: Convert Nikon .NEF files to Adobe .DNG or .TIFF using Adobe DNG Converter or LightCraft before importing.

---

4. MCP & Automation Connection Errors#

automation command 'image.applyDataSet' uses ambient filesystem paths and is disabled#

• Cause: Strict security fail-closed mode introduced in v0.2.0+ (Issue #806). Scripts and AI Agent MCP callers cannot access arbitrary filesystem locations.
• Solution: You must explicitly whitelist input and output paths on startup:

  photocraft --automation-read-root /path/to/workdir --automation-write-root /path/to/output
  

  Or declare environment variables:

  export PHOTOCRAFT_AUTOMATION_READ_ROOT="/path/to/workdir"
  export PHOTOCRAFT_AUTOMATION_WRITE_ROOT="/path/to/output"
  

Desktop Automation Control Channel Connection Refused#

• Cause: Missing per-launch security token.
• Solution: PhotoCraft prints a unique one-time token in the terminal on startup. Copy and pass this token when initializing your automation client or MCP bridge.