---
title: Installation errors
description: Every error message the NexCMP installer can print, what causes it and how to fix it — requirements, license activation, download verification, services and nginx/TLS.
url: https://nexcmp.com/docs/troubleshooting/installation-errors/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Installation errors

The installer stops at the first fatal problem and prints a red line starting with `✗`. Fix the cause and **run the same command again** — the installer is safe to repeat. Informational lines start with `•`, successful steps with `✓`.

## Machine checks

| Message | Cause | Fix |
|---|---|---|
| `must be run as root (sudo)` | Not running as root | Prefix the command with `sudo`, or run as root. |
| `only Ubuntu 22.04/24.04 is supported (this host: …)` | Another distribution or version | Use an Ubuntu 22.04 or 24.04 server. |
| `only x86_64 is supported` | ARM or other CPU | Use an x86_64 server. |
| `requires ≥ 2 GB RAM (host has … MB)` | Too little memory | Add RAM. |
| `requires ≥ 8 GB free disk space on / (… GB available)` | Root filesystem nearly full | Free space or enlarge `/`. |
| `missing --license` / `missing --domain` | First install without those parameters | Pass both — see [Installation](https://nexcmp.com/docs/getting-started/installation/#parameters). |
| `unknown argument: …` | Typo in a parameter | Check spelling; run with `--help`. |
| `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | The package manager is locked | Wait a few minutes (a fresh Ubuntu runs automatic updates after boot) and re-run. |
| `… is a symlink — aborting` | `/opt/nexcmp` or `/etc/nexcmp` is a symbolic link | Replace it with a real directory — the installer refuses symlinks for security. |

## License activation

| Message | Cause | Fix |
|---|---|---|
| `cannot connect to https://nexcmp.com` | No outbound HTTPS to the license server | Check DNS, firewall and proxy on the server: `curl -I https://nexcmp.com`. |
| `license activation failed (HTTP …): <message>` | The license server rejected the key | Read the message: wrong key, domain not matching the license, license suspended or revoked. Check the license page at [nexcmp.com/licenses](https://nexcmp.com/licenses). |
| `no release available for this license yet` | The license has no downloadable release | Contact sales; see [Support](https://nexcmp.com/docs/troubleshooting/support/). |

## Download and verification

| Message | Cause | Fix |
|---|---|---|
| `failed to download release X` | Network problem during download | Re-run. |
| `sha256 mismatch (… ≠ …)` | The file arrived damaged or was altered | Re-run; if it repeats, a proxy may be rewriting downloads — try from another network. |
| `release X is unsigned — refusing to install` | The server delivered no signature | Never bypass; contact support. |
| `INVALID SIGNATURE for version X — aborting` | The Ed25519 signature does not verify | Do **not** install. Contact support — this means the file is not an official release. |
| `openssl failed to read public key` | Very old or broken OpenSSL | Update the `openssl` package. |
| `invalid version: …` | Unexpected data from the server | Re-run; contact support if it persists. |

## Service start

| Message | Cause | Fix |
|---|---|---|
| `service failed to start — check: journalctl -u nexcmp -n 50` | The panel did not answer `/healthz` within 3 minutes | Read the journal. Common causes: the port (default 3000) is already used (`ss -ltnp | grep 3000`) — re-install with `--port`; files owned by root in `/var/lib/nexcmp` — run `sudo nexcmp fix-owner`. |

## nginx and TLS

| Message | Cause | Fix |
|---|---|---|
| `DNS <domain> does not point to <IP> (nor to Cloudflare) — skipping nginx/TLS` | The A/AAAA record is missing or wrong | See [DNS and Cloudflare](https://nexcmp.com/docs/getting-started/dns-and-cloudflare/), then re-run. |
| `certbot could not get a certificate yet — re-run the installer once DNS has settled` | Let's Encrypt validation failed (port 80 blocked, DNS not propagated, rate limit) | Open port 80, wait for DNS, re-run. Check `/var/log/letsencrypt/letsencrypt.log`. |
| `certbot could not renew now — keeping the existing certificate` | Temporary renewal failure | Harmless; re-run later. |
| `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | Another nginx site conflicts (same `server_name`, duplicate settings) | Run `sudo nginx -t` and fix the conflict, then re-run. |
| `apt-get could not install nginx` / `certbot`, or `E: Failed to fetch … 404 Not Found` | Package manager locked, or the server's package index is stale (typical on a template image that has not been updated for a while) | Run `sudo apt-get update`, wait for any other apt process to finish, then re-run the installer. |
| `openssl could not create the self-signed certificate` | OpenSSL problem | Update `openssl`; re-run. |

## After installation

| Symptom | Cause | Fix |
|---|---|---|
| Browser cannot open `https://<domain>` | DNS or TLS not ready | `sudo nexcmp status`; use [emergency access](https://nexcmp.com/docs/getting-started/cli-reference/#emergency-access). |
| `ERR_TOO_MANY_REDIRECTS` | Cloudflare SSL mode **Flexible** | Set **Full (strict)** — [details](https://nexcmp.com/docs/getting-started/dns-and-cloudflare/). |
| Wizard says "setup code" is wrong | Typo or a code from an earlier install | Run `sudo nexcmp status` and copy the current code. |
| License shows HTTP 421 | Files in `/var/lib/nexcmp` owned by root | `sudo nexcmp fix-owner`, then `sudo systemctl restart nexcmp`. |