Installation errors and how to fix them

The installer and the first-run wizard stop with a short message. Find its text on this page, fix the cause and repeat the same installation command or the same action in the wizard. A rerun continues the installation you started: saved settings and data stay in place.

Where to check the installation state

The installer prints the message to the terminal, and the wizard shows it on its page. Check the installation state on the server:

sudo micatorctl status
sudo micatorctl check
sudo systemctl status micator-setup.service
sudo journalctl -u micator-setup.service -n 50
sudo docker ps -a

• micatorctl status prints the version and the phase. Phases when you install through the wizard: awaiting_setup — the wizard is waiting for setup, starting — the tracker start has begun, ready — the tracker is ready.
• micatorctl check checks readiness once. Success is “Services and HTTPS are responding.” («Сервисы и HTTPS отвечают.») Until you click Launch tracker («Запустить трекер») in the wizard, the command answers “Operation not completed: FileNotFoundError” («Операция не завершена: FileNotFoundError»): the settings are not saved yet.
• journalctl shows the reason if the wizard service did not start.
• docker ps -a shows the containers and their state. Container log: sudo docker logs --tail 50 NAME; take the name from the NAMES column.

The micatorctl command appears once the server is prepared; when you install in the terminal, it appears after the tracker starts successfully. If there is no micatorctl command on the server, use trackerctl: that is what the first releases called the command, and micatorctl appears next to it after you update the installation service. In the examples the installation directory is /opt/micator. If you installed with --path, use your own directory. In installations made before this release, the default directory is /opt/tracker and the wizard service is tracker-setup.service; see names in such installations.

File and service locations are listed on Installation files, ports, services and logs.

Startup errors: permissions, system, resources

What the installer checks on the server is described on Server requirements and preparation.

“Command … failed (N).” («Команда … завершилась ошибкой (N).»)

A system command failed: apt-get, curl, docker or systemctl. The message contains only the command name and the exit code. Details are not printed because they may contain passwords. In the wizard, a command error during the tracker start looks the same.

1. For apt-get, run sudo apt-get update: the command will show the cause.
2. For curl, check that the server can open https://download.docker.com.
3. For docker, check the Docker service: sudo systemctl status docker.
4. Repeat the same installation command.

“Operation not completed: …” («Операция не завершена: …») and “Could not finish the setup. Data is saved; try again.” («Не удалось завершить настройку. Данные сохранены; повторите попытку.»)

An unexpected error. In the terminal, the error type follows the colon, for example TimeoutExpired — the command did not finish within the allotted time. The second message is shown by the wizard.

1. Repeat the installation command or the action in the wizard.
2. If the message appears again, check the state with the commands from Where to check the installation state.

Request rejected in the wizard behind Cloudflare

If the wizard is open on an HTTPS domain but says “The request must come from the setup wizard” («Запрос должен выполняться из мастера установки») or “The request reached the server over HTTP” («До сервера запрос дошёл по HTTP»), check that SSL/TLS → Overview → Full (strict) is selected in Cloudflare for this zone. In Flexible mode the connection from Cloudflare to the server stays HTTP, and the wizard does not accept such a request. After changing the mode, repeat the action on the panel domain.

Do not turn off the Origin and HTTPS checks on the server. If Full (strict) is already selected, check that any other reverse proxy also passes requests to Micator over HTTPS.

Release signature and contents

The installer downloads the release archive, checks its signature and only then unpacks it. After that it checks every file against the signed list.

What to do:

1. Repeat the installation command: the archive is downloaded again on every run.
2. If the message appears again, download the installer again: curl -fsSLo install.sh https://install.micator.com/install.sh.
3. Check the release without installing it: sudo bash install.sh --verify-only. Success is the line “Release contents verified: …” («Состав выпуска проверен: …»).
4. Run sudo bash install.sh.

If the signature fails even with a freshly downloaded installer, do not install this archive.

Busy ports, non-empty directory, previous installation

“Port 80 is busy.” («Порт 80 занят.») and “Port 443 is busy.” («Порт 443 занят.»)

Another program is already listening on this port on the server. When you install in the terminal, the text is different: “Port 80 is used by another web server.” («Порт 80 занят другим веб-сервером.»)

1. Find the program: sudo ss -ltnp | grep -E ':(80|443) '.
2. Stop it.
3. Disable its autostart.
4. Repeat the installation command.

“The directory is not empty; installing over existing data is not allowed.” («Каталог не пуст; установка поверх существующих данных запрещена.»)

The installation directory (/opt/micator by default) already contains files, and there is no started installation in it. When you install in the terminal: “The directory is not empty. Installing over Git, data or an unknown system is not allowed.” («Каталог не пуст. Установка поверх Git, данных или неизвестной системы запрещена.»)

Use a clean server or specify another directory: sudo bash install.sh --path /opt/micator-2. On every later installer run, specify the same --path.

“The server already has Micator resources.” («На сервере уже есть ресурсы Micator.»)

Docker on the server already has containers, volumes or networks of the micator project or the tracker project — that is the project name in installations made before this release. When you install in the terminal: “The server already has Micator resources. Automatic takeover is not allowed.” («На сервере уже есть ресурсы Micator. Автоматический захват запрещён.») Similar messages:

• “The server already has Micator volumes; automatic assignment is not allowed.” («На сервере уже есть тома Micator; автоматическое присвоение запрещено.») — volumes named micator_… or tracker_… were found.
• “The first-run service name is already taken.” («Имя службы первого запуска уже занято.») — a container named micator-setup-edge or tracker-setup-edge exists.

The installer does not take over or delete resources it does not own, and it installs the tracker only on a server without them. To see what was found:

sudo docker ps -a --filter label=com.docker.compose.project=micator
sudo docker ps -a --filter label=com.docker.compose.project=tracker
sudo docker ps -a --filter name=setup-edge
sudo docker network ls --filter label=com.docker.compose.project=micator
sudo docker network ls --filter label=com.docker.compose.project=tracker
sudo docker volume ls

“A different release is installed. The wizard does not update a running tracker.” («Установлен другой выпуск. Мастер не обновляет работающий трекер.»)

The installation in this directory was started or completed by a different release, not the one the installer downloaded. When you install in the terminal: “A different release is installed. The installer does not update or roll back existing databases.” («Установлен другой выпуск. Установщик не обновляет и не откатывает существующие базы.»)

• If the tracker is already running, update it in the panel: Settings → Updates («Настройки → Обновления»). Details are on Updating the tracker from the panel.
• If the installation is not finished, continue it with the same install.sh file you started with. Each installer file downloads its own release.

The public IP was not detected

Message: “Could not determine the public IPv4. Pass --setup-ip with the server IP.” («Не удалось определить публичный IPv4. Передайте --setup-ip IP сервера.»)

The wizard opens at the server's public IPv4 address. The installer looks for such an address on the network interfaces. If the interfaces only have private addresses, auto-detection does not work.

1. Find the server's public IPv4 in your hosting control panel.
2. Run the installer with this address: sudo bash install.sh --setup-ip 203.0.113.10. Replace the address in the example with your own.

The address must be a public IPv4. A private address such as 10.0.0.5 or 192.168.1.10 and IPv6 addresses are not accepted.

The wizard does not open

“The wizard is not available yet. Check micator-setup.service and rerun the installer.” («Мастер ещё недоступен. Проверьте micator-setup.service и повторите установщик.»)

The wizard service did not respond to 30 checks in a row made one second apart.

1. Check the service state: sudo systemctl status micator-setup.service.
2. Check its log: sudo journalctl -u micator-setup.service -n 50.
3. Make sure Docker is running: sudo systemctl status docker.
4. Repeat the installation command. The access code stays the same.

The terminal showed a link, but the page does not open in the browser

The installer does not open ports in an external firewall.

1. Open inbound TCP ports 80 and 443 in the server firewall and in your hosting control panel.
2. Open the link exactly as it is, with http://: at the IP address the wizard works without HTTPS.

“Enter the access code from the installer.” («Введите код доступа из установщика.») and “The access code is invalid.” («Код доступа не подходит.»)

The code was not entered or was entered with a typo. The link with the code and the code itself are saved in a file on the server:

sudo cat /opt/micator/setup-access.txt

“Invalid wizard address.” («Неверный адрес мастера.»)

The wizard responds only at the server IP and at the panel domain. Open the link from the terminal, or https://panel.example.com/setup/ with your own panel domain.

“The login and password can be set only over HTTPS on the panel domain.” («Логин и пароль задаются только по HTTPS на домене панели.»)

Step 2 was opened by IP or without HTTPS. Open https://panel.example.com/setup/ with your own panel domain and enter the access code.

Domain and DNS errors in the wizard

After an error, the wizard stays on the “Connect your domains” («Подключите домены») step. Fix the fields or DNS and click Check and continue («Проверить и продолжить») again.

If the domain “does not point to this server yet”:

1. Check that the A record points to the server IP from the wizard link.
2. Check the AAAA record: if there is one, it must also point to this server.
3. Open inbound TCP port 80.
4. Turn off the HTTP-to-HTTPS redirect on your proxy while you set up: the wizard checks the domain over HTTP and does not follow redirects.

When you install in the terminal, only the presence of the domains in DNS is checked. Message: “The domain does not resolve in DNS yet: …” («Домен ещё не разрешается в DNS: …»).

HTTPS is not ready

Message: “HTTPS is not ready yet. Check DNS, ports 80/443 and the Full (strict) mode in Cloudflare, then try again.” («HTTPS пока не готов. Проверьте DNS, порты 80/443 и режим Full (strict) в Cloudflare, затем повторите.»)

The domains passed the check but did not respond over HTTPS within 60 checks made 3 seconds apart. The wizard moves on to step 2 and opens https://panel.example.com/setup/. The message is shown on that page. Until the certificate is issued, the page does not open.

1. Make sure inbound TCP ports 80 and 443 are open from the internet, not only from your own address.
2. Check that both domains still point to this server.
3. If the domains go through Cloudflare, turn on the Full (strict) encryption mode.
4. Reload https://panel.example.com/setup/ with your own panel domain.
5. When the page opens, continue from step 2. The domains cannot be changed at this step.

Services are not ready: “Not ready: …”

Message: “Not ready: …. Fix the cause and repeat the command; data is saved.” («Не готовы: …. Исправьте причину и повторите команду; данные сохранены.»)

After the start, the installer checks readiness up to 60 times, 3 seconds apart. In place of the ellipsis, the message names the part where the check stopped.

The commands for viewing containers and logs are in Where to check the installation state.

What to do:

1. Fix the cause on the server.
2. In the wizard, on the “You need to retry the launch” («Нужно повторить запуск») screen, click Retry launch («Повторить запуск»). The settings are saved, so you do not need to enter the owner login and password again.
3. When you install in the terminal, repeat the same command with the same parameters.

sudo systemctl restart micator-setup.service

The GeoIP database was not downloaded

Message: “Could not download GeoIP. Put city.mmdb into data/geoip and repeat the installation.” («Не удалось загрузить GeoIP. Положите city.mmdb в data/geoip и повторите установку.»)

The installer downloads the DB-IP City Lite database from download.db-ip.com: first for the current month, then for the previous one. The message appears when both downloads fail. Put the database in place manually:

1. On your computer, download https://download.db-ip.com/free/dbip-city-lite-YYYY-MM.mmdb.gz. Replace YYYY-MM with the current year and month, for example 2026-10.
2. Unpack the archive.
3. Rename the file to city.mmdb.
4. Put it on the server: /opt/micator/data/geoip/city.mmdb.
5. Allow the file to be read: sudo chmod 644 /opt/micator/data/geoip/city.mmdb.
6. Click Retry launch in the wizard, or repeat the installation command in the terminal.

If a file larger than 1 KB is already in place, the installer does not download the database.

Server reboot during setup

You can close the wizard tab: the setup runs on the server. A server reboot does not reset it either.

• The micator-setup.service service starts together with the server and continues from the saved step.
• If the reboot happened during the domain check, the check starts again with the same domains.
• If Launch tracker was already clicked at step 2, the start continues without your involvement.
• The message “The start was interrupted before the settings were saved. Repeat the restore of the verified backup.” («Запуск прервался до сохранения настроек. Повторите восстановление проверенной копии.») appears if the reboot interrupted the beginning of a restore from a backup. Open the Restore from a backup («Восстановить из резервной копии») block and start the restore again.

To return to the wizard, open the same link. Until the wizard is finished, the link is saved in /opt/micator/setup-access.txt. The wizard screens and the step 2 field errors are described on First-run wizard.

Owner password

You choose the owner password yourself: in the wizard at step 2 or in the terminal. The tracker does not write it to files and does not show it, so the old password cannot be recovered.

• Messages of the owner form in the wizard, for example “Passwords do not match.” («Пароли не совпадают.»), are covered on First-run wizard.
• Messages of the terminal installation and of the --owner-password-file file are in the table on install.sh parameters and installing in the terminal.
• If the password is forgotten, root sets a new one on the server with sudo micatorctl owner-password — see New owner password.

Parallel and repeated runs

Running sudo bash install.sh again before the wizard is finished prints the same link with the same code. Once the wizard is finished, it is closed: the /setup/ address on the panel domain redirects to the login page.

If the panel shows “Update the installation service on the server first” («Сначала обновите службу установки на сервере»), it is not an installation error. Follow the steps on Updating the installation service.