Start with the exact symptom, operating system, processor, Launcher version and package filename. The official Launcher is early alpha. The checks below follow its README; they are recovery instructions to try, not fixes tested on your computer.
Save open work and keep project files. Record the current and offered versions, full error text, package format and whether the problem affects the Launcher itself or one Craft app. These identify different failure points. Official README snapshot ↗
This guide was researched on 20 October 2026 against README commit 7c7271e5f629. It does not pin a latest release number; official releases ↗ determine available packages.
All branches below come from the official installation, updating and platform notes ↗. They do not imply a maintainer-confirmed fix for every occurrence.
Check the OS and processor against the same official release’s assets. The README documents Windows 10/11 x64, ARM64 and x86 variants; a universal macOS 11+ DMG; and Linux builds with architecture and glibc requirements. Use the installer picker on the main Launcher guide.
The filename, architecture and format match your computer; the release supplies SHA256SUMS.txt.
If this fails: If that combination is absent, use the release list rather than renaming another architecture’s file. Do not substitute a third-party mirror.
Keep: Keep the exact installer name, release tag and published checksum.
Record the exact error and compare the file with SHA256SUMS.txt from that release. Retry the official asset only after noting whether it was a partial download or a checksum mismatch.
The downloaded bytes match the published checksum before installation.
If this fails: Stop using a mismatched file; attach the error and log to an issue if an official fresh download still fails. Do not disable verification.
Keep: Retain the log and checksum comparison; do not retain a suspect installer as the working copy.
Record the operating system, processor, exact Launcher release and package filename. Check that build’s documented OS and runtime requirements. Capture the complete startup or system security message; on Linux, launch the exact AppImage from a terminal after the documented executable-bit check to retain its output.
Either the window opens or you have a specific startup diagnostic to compare with the official package requirements and logs.
If this fails: The README does not provide one universal repair for Windows or macOS startup failures. Keep the security message and use the official issue route below; do not disable platform security or delete application data to try an undocumented fix.
Keep: Startup message, release/package identity and available log.
Save the project, close the target Craft app normally, then retry the update. The README says running apps are never replaced and updates keep the installed package format.
The target app is closed during replacement, then reopens with its saved project intact and the expected installed version.
If this fails: If the same error remains, inspect the log and use the individual app’s official release as a documented manual installation route. Do not remove project folders.
Keep: Preserve the saved project, current version, offered version and log.
Check the CPU architecture and required glibc version in the release README. Mark the downloaded AppImage executable with chmod +x on its exact path, then run it from a terminal to capture the message.
The launcher window opens, or the terminal supplies an observable dependency or graphics error.
If this fails: Use a matching official .deb or .rpm for your distribution if appropriate. For a Nix build failing to load host GPU drivers, the README describes nixGL or using a release package; avoid treating that as a universal AppImage fix.
Keep: Keep terminal output, distribution version, architecture and package filename.
The README says GNOME needs an AppIndicator extension for its StatusNotifierItem tray icon. Flatpak installs may run apps inside the sandbox when the host lacks Flatpak; inspect the documented sandbox location rather than assuming a host install failed.
The main window still provides the catalog; the installation location matches the chosen packaging route.
If this fails: Use the officially recommended AppImage, .deb or .rpm route if the Flatpak boundary prevents the intended workflow. Avoid broad sandbox permission changes.
Keep: Record desktop environment, packaging format and the installation path.
Find the app’s row in the Launcher Grid or Table view and compare its installed indicator/version with the standalone app. The README says manually installed apps are detected in normal system locations: /Applications on macOS, the Windows application installation, or the Linux package location. Check the exact location in the official platform table. For a portable Windows copy, inspect the portable folder; for Flatpak, distinguish a host installation from the documented sandbox fallback. Try opening the existing app normally without moving its project files.
You can distinguish a missing installation from a working standalone app whose path or version is not being detected by the Launcher.
If this fails: If the standalone app opens but its Launcher row stays uninstalled, retain its path, package type, version and Launcher log and report those facts. No general force-rescan or path-repair control is documented in the reviewed README; do not invent one or reinstall/delete project folders blindly.
Keep: App name, actual install location, package type, working standalone version, Launcher row state and log excerpt.
The README places logs/artcraft-launcher.log beneath ~/Library/Application Support/ArtCraft Launcher on macOS, %LOCALAPPDATA%\ArtCraft Launcher on Windows, ~/.local/share/artcraft-launcher on Linux, or ArtCraftLauncherData beside a Windows portable executable. Previous runs use artcraft-launcher.1.log and artcraft-launcher.2.log. Logging paths ↗
Include the OS, architecture, Launcher and target-app versions, exact action, error and relevant log excerpt in the official issue tracker ↗. Review logs for private file paths before posting publicly. A report is not a guarantee that the issue has been fixed. Back to Launcher Guide →
Official sources checked 20 October 2026. Test results are limited to the versions, environment and files stated above.
Craft Apps Guide