Self-hosted install

Errors and solutions

Message or symptom, its cause and the fix.

v1.0.0 CZ

Errors and solutions

Docker is not installed. Install it (https://docs.docker.com/engine/install/) or re-run with --auto to install automatically.

Cause: Docker is missing on this machine.

Fix:

  1. Install Docker Engine (Linux) or Docker Desktop (macOS, Windows).
  2. Run the installer again.

Docker did not start within 60 s. Start it manually and re-run.

Cause: The Docker service did not come up in time.

Fix:

  1. Start Docker (on Linux: sudo systemctl start docker).
  2. Check that docker info works, then re-run the installer.

Docker Desktop did not start within 120 s. Open it manually and re-run.

Cause: Docker Desktop on macOS is not running.

Fix:

  1. Open Docker Desktop and wait until the engine is running.
  2. Run the installer again.

Homebrew is required to install Docker on macOS. Install it first: https://brew.sh

Cause: The automatic install on macOS uses Homebrew to install Docker Desktop.

Fix:

  1. Install Homebrew from https://brew.sh or install Docker Desktop yourself.
  2. Run the installer again.

Docker requires sudo on this session. Log out and back in, then re-run.

Cause: Your user was just added to the docker group and the session does not know it yet. The same cause gives permission denied on the Docker socket.

Fix:

  1. Run sudo usermod -aG docker $USER if the group is missing.
  2. Log out and back in.
  3. Run the installer again.

Unsupported Linux distribution. Install Docker manually: https://docs.docker.com/engine/install/

Cause: The installer cannot install Docker on this Linux distribution.

Fix:

  1. Install Docker Engine and the Compose plugin following the Docker documentation.
  2. Run the installer again.

Docker Desktop did not become ready within 120 seconds.

Cause: On Windows the Docker engine is not running. Typical reasons: the com.docker.service service is stopped, WSL2 is not installed, virtualization is disabled in the BIOS, or Docker Desktop is switched to Windows containers.

Fix:

  1. Reboot if Docker Desktop was just installed, and check the Docker Desktop icon in the system tray.
  2. Make sure WSL2 is installed (wsl --status), virtualization is enabled in the BIOS and Docker Desktop uses Linux containers.
  3. Check that docker ps works, then re-run the installer.

Container exits with code 137, or Docker Desktop becomes very slow

Cause: The container ran out of memory and was killed.

Fix:

  1. Give Docker at least 16 GB of memory (Docker Desktop → Settings → Resources; on Windows the memory value in .wslconfig).
  2. Close other heavy programs and restart with docker compose restart.

Failed to load Docker image — archive may be corrupt (or docker load stops with a write error)

Cause: The disk is full, or the package file was damaged during the copy.

Fix:

  1. Free disk space (at least 50 GB free is required).
  2. If the disk was fine, copy the release package again and re-run the installer.

Port 3333 is already in use on this host.

Cause: Another program uses the port. The automatic installer picks a free port itself.

Fix:

  1. Run the automatic installer, or set another port in AITM_PORT in docker/.env.
  2. Restart with docker compose up -d.

Package authenticity could NOT be verified (no network access to www.aitm.cz ...)

Cause: A corporate proxy or firewall blocks aitm.cz and license.aitm.cz.

Fix:

  1. Ask your network administrator to allow aitm.cz and license.aitm.cz.
  2. Run the installer again.

Checksum mismatch for ... / Signature verification FAILED for checksums-v...

Cause: The package is damaged or incomplete.

Fix:

  1. Download the release package again.
  2. Extract it into a new folder and run the installer again.

Package version X is older than deployed version Y. Refusing to downgrade.

Cause: The installer only installs the same or a newer version than the one that is running.

Fix:

  1. Download the newest release.
  2. Run its installer.

A staged update is already in progress ...

Cause: A previous update was started and not finished.

Fix:

  1. Run cutover-docker.sh (Windows: cutover-docker.ps1) to complete it.
  2. Or run it with --abort (Windows: -Abort) to discard it, then start the update again.

Health check timed out — containers may still be starting. Check: docker compose ps

Cause: The first start takes a minute or two; the container shows starting or unhealthy until it is ready.

Fix:

  1. Run docker compose ps in the docker folder and wait a moment.
  2. If it stays unhealthy, read docker compose logs -f.

HTTP 423 when opening AITM

Cause: Expected: AITM is locked until a license or the trial is activated.

Fix:

  1. Open Settings → License.
  2. Activate your key or start the 7-day trial.

License activation fails, or the trial says the device is already activated

Cause: The license is already used on the maximum number of devices, or this device already had a trial.

Fix:

  1. Sign in to your account on aitm.cz and check the activations of your license.
  2. If it does not help, contact support.

Logs and support

The installer prints the path of its log file (install_<time>.log next to the scripts). The running application writes to docker compose logs. If you cannot solve the problem, contact us and attach the installer log.