Start by separating four failures that look alike: the application cannot install, the renderer crashes, a file format is only partly supported, or a required font is missing. PhotoCraft is early alpha, so the safest workflow is to reproduce each issue with a copy, record the release and environment, and report the smallest file that demonstrates it rather than flattening the evidence away.
Read the Windows install guide All guides
Written against the build verified on 2026-10-14.
Write down the PhotoCraft release tag, operating system, CPU architecture, GPU and driver, file format and whether the problem happens with a new blank document.
Work from a copy. Do not overwrite the only PSD, HEIC or project file while trying a different renderer, export or release.
Try a small PNG and a small document with one layer. If that works, add the original file, layers, effects and fonts back one at a time.
Do not change the app, driver and file at the same time. A single changed variable gives the upstream issue report something useful to act on.
| Problem | Likely boundary | Safe next step |
|---|---|---|
| Installer is blocked | Windows policy, SmartScreen or a mismatched asset | Recheck architecture, upstream release URL and checksum; do not use a random mirror |
| AppImage or package does not start | Missing runtime, FUSE or graphics dependency | Try the package format for the distribution and capture the terminal error |
| Launch crashes before a document opens | Renderer, driver or build issue | Test a software renderer or updated driver, then report the exact release and GPU |
| Only one large file crashes | Memory, document feature or imported asset | Reduce a copy until the smallest reproducer opens |
Do not turn a successful PNG conversion into a claim that PhotoCraft natively supports every HEIC variant. HEIC is a compatibility test: check the current release notes and repository issue guidance, then try a copy of the file. If the current build cannot open it, convert the copy to PNG or TIFF with a tool you already trust, keep the original HEIC unchanged and report the codec, bit depth, metadata and failure message with the release tag. The conversion is a fallback, not proof of native HEIC support.
A PSD is a document structure, not just a final bitmap. Check whether the file uses groups, smart objects, adjustment types, text effects or blend modes that the current release does not round-trip. Compare the layer tree before editing, keep the source file, save a PhotoCraft copy and export a flat reference. If the structure differs, report the smallest PSD that reproduces it instead of exporting a flattened file and losing the evidence.
A missing or substituted font changes layout even when the image editor itself is working. Confirm the font name and weight, install it only from a source you trust, restart the application if its font list is cached and compare the result on the target machine. For delivery, keep an editable text version and make a separate outlined or rasterized handoff only when the workflow requires it. Never silently replace a client font and call the file identical.
If a blank document fails, start with the installation, renderer and driver boundary. If a blank document works but a PNG fails, inspect the file dimensions, colour profile and decoder path. If PNG works but PSD or HEIC fails, treat it as a format-compatibility question and preserve the source. If the document opens but text changes, inspect fonts before changing the renderer. If only export fails, compare the native project save with a flat PNG and determine whether the issue is the chosen format or the document itself. This ordering prevents five unrelated changes from being reported as one vague crash.
A workaround is acceptable when it preserves the business result and clearly records what was lost. Converting an HEIC copy can produce an editable raster input, but it may remove original metadata. Flattening a PSD can make an image deliverable, but it removes the layer tree. Outlining text can stabilise a vector handoff, but it removes live text editing. Keep both the original and the workaround output, state the conversion tool and release, and do not rewrite the workaround as native support in a tutorial or comparison.
Stop testing the alpha build when the file is a deadline-critical original, the conversion is changing colour or layers, or the same failure survives a minimal reproduction on a clean machine. Use the mature tool already approved for that job, keep the PhotoCraft issue evidence separate and return to the new release when the upstream project documents a fix. The point of troubleshooting is to isolate a boundary, not to force an early tool into a role it cannot yet guarantee.
Do not assume complete HEIC support from the existence of an image import feature. Test the exact HEIC variant against the release you use. If it fails, preserve the original and use a verified conversion only as a fallback.
PSD compatibility depends on the specific structures and effects in the file. Check the layer tree and report a minimal example; opening the composite alone does not prove a safe round trip.
First separate a blank document, a small PNG and the original file. Record the renderer, GPU, driver and release, then report the smallest case that still crashes.
The required family or weight may not be installed or discovered on that machine. Confirm the font identity, install it from a trusted source, restart if needed and keep an editable copy before outlining text.
