---
title: Installer Won't Run or Fails Verification
summary: Docker missing, permission errors, AppImage launch failures, port conflicts, and signature verification problems, with the fix for each.
date: 2026-09-10
---

# Installer Won't Run or Fails Verification

Docker missing, permission errors, AppImage launch failures, port conflicts, and signature verification problems, with the fix for each.

## "Docker is required but not installed"

Install Docker Engine (Linux) or Docker Desktop (macOS/Windows) from docker.com, then verify with `docker info` and `docker compose version`.

## "Permission denied" running Docker on Linux

Your user isn't in the `docker` group yet: `sudo usermod -aG docker $USER`, then log out and back in and confirm with `groups | grep docker`.

## AppImage won't launch on Ubuntu 22.04+

Install the FUSE 2 compatibility library: `sudo apt install libfuse2t64` on Ubuntu 24.04+, or `sudo apt install libfuse2` on Ubuntu 22.04. If you'd rather not install it, run the AppImage with `--appimage-extract-and-run` instead.

## Port conflict (9500, 9100, or similar already in use)

`install.sh` scans for a free port automatically, starting from the preferred one and incrementing. Check `~/.heartbeatagents/.env` to see which ports it actually allocated.

## GPG signature verification fails

1. Confirm you imported the right public key: `gpg --list-keys --fingerprint ops@mosaicsingularity.com`. Expected fingerprint: `3041 1399 8510 1531 C54B 0498 1009 78CA B0A0 5886`.
2. If the fingerprint doesn't match, don't trust the package. Someone may have tampered with the key or the file.
3. Report suspected tampering to `ops@mosaicsingularity.com`.

## macOS says the app "is damaged" or "cannot be opened"

This shouldn't happen since the app is Apple-notarized. If you see it:
1. Confirm you downloaded from the official release page, not a mirror.
2. Check the notarization staple: `xcrun stapler validate HeartBeatAgents.app`.
3. If the staple is valid but macOS still refuses, the download itself was probably corrupted. Re-download and verify its SHA256 checksum.

## Windows SmartScreen warning

The installer is EV-signed, so SmartScreen should accept it without a warning. If you see one, verify the signature with `Get-AuthenticodeSignature HeartBeatAgents-Setup-<version>.exe` in PowerShell: `Status` should read `Valid` and the signer should include Mosaic Singularity Inc. If it doesn't, don't run the installer; report it to `ops@mosaicsingularity.com`.

## Related

- [Installation](/en/docs/getting-started/installation): the installers and checksums these issues apply to
- [Docker Desktop Won't Start](/en/docs/troubleshooting/docker-wont-start): a running install that won't launch, as opposed to one that won't install