Troubleshooting

Use this section when GitComet is not behaving as expected.

In this section:

• Crash Reports

Before anything else

Check whether the problem is already fixed in a newer version: the changelog lists every release, and Download has the install instructions for each platform.

Git is missing or too old

GitComet requires Git 2.50 or newer. In Settings → Git executable, check the version and path reported by the app. The desktop application's environment can differ from your terminal's environment.

Choose System PATH to use automatic discovery, or Custom executable to select Git explicitly. Browse to the executable, or enter its path and choose Use Path. If GitComet opens a Git-unavailable screen, use its Open Settings action to correct the path.

The Linux window does not open

Launch GitComet from an active Wayland or X11 desktop session. Under WSL, use WSLg. A Wayland-only session needs both WAYLAND_DISPLAY and XDG_RUNTIME_DIR; X11 needs DISPLAY.

If a manually installed binary reports a missing XCB or XKB library on Debian or Ubuntu, install libxcb1, libxkbcommon0, and libxkbcommon-x11-0. The Linux installation guide includes the command and alternatives for systems that cannot run AppImages.

Fetch, pull, push, or clone fails

Check the remote URL and the authentication prompt. For SSH remotes, confirm that the matching public key is registered with your Git host and that the private key is available to your SSH setup. See SSH Keys.

Settings → Security / Privacy controls allowed Git transport protocols. GitComet can also ask you to trust a repository before running submodule operations. Review the prompt and the repository involved when an operation is blocked.

A merge result cannot be saved

The merge view blocks Save while the result still contains unresolved conflicts. Use Shift+F2 / Shift+F3 to find the remaining conflicts, choose the intended inputs or edit the output, then save. In a repository, Save & stage also marks the file resolved in Git. See interactive conflict resolution.

A custom theme does not appear

Place the .json bundle in the user themes directory, declare "schema_version": 2, and give it a filename and theme key that do not collide with a built-in theme. Invalid bundles are skipped with a path and reason in the application diagnostics. See theme validation.

Report a reproducible problem

Include your GitComet version, operating system, Git version, installation method, exact error, and steps to reproduce in a GitHub issue. For an unexpected exit, use the crash report and log files.