Installation Fails

Installation Fails

The installer stops with a clear red message when something is wrong. This page lists those messages and how to fix each one. In every case, fix the cause and run the installer again.

curl -fsSL https://vinzapanel.com/install.sh | sudo bash

The full output of the main installation step is written to /var/log/vpanel-install.log. Check its end first:

sudo tail -n 50 /var/log/vpanel-install.log

"Please run as root"

The installer must run as root. Keep sudo in front of bash, as in the command above.

"Ubuntu 20.04+ required" or "Unsupported OS"

VinzaPanel needs Ubuntu 20.04 or newer (22.04, 24.04 and 26.04 are tested). Debian is accepted with a warning (proceed with caution); other distributions are refused. Check your system:

cat /etc/os-release

If it is older or another distribution, reinstall the server with a current Ubuntu LTS. See System Requirements.

"Unsupported architecture"

Only x86_64 and aarch64 (ARM64) are supported. Check with uname -m.

"Insufficient disk space. Required: 2 GB"

The root filesystem needs at least 2 GB free before installing. Check and free up space, or grow the disk:

df -h /

"DNS resolution failed" or "No outbound internet"

The installer downloads packages and the panel release, so the server needs working DNS and outbound HTTPS. It tells you which one is broken:

• DNS resolution failed … but the internet IS reachable by IP — set a working resolver and re-run:

  echo 'nameserver 8.8.8.8' | sudo tee /etc/resolv.conf

  For a permanent fix, add nameservers in /etc/netplan/*.yaml and run sudo netplan apply.
• No outbound internet (cannot reach 1.1.1.1:443) — check the gateway, NAT or your provider's firewall, then re-run.
• Cannot reach the package mirror — same cause as above, for the Ubuntu mirror.

"apt failed — retrying over IPv4 only"

This is a warning, not a failure: some VPSes have broken IPv6, so the installer retries apt over IPv4. If it then stops with Failed to install required packages, the apt error just above it names the package and the reason.

Waiting on the package lock

Freshly booted servers often run automatic updates. The installer waits for the dpkg lock instead of failing, so a pause of a few minutes at the start is normal.

Python errors

The installer installs Python 3.12 itself (from the deadsnakes repository on Ubuntu), so you normally do not need to do anything. If you see python3 not found or No usable Python 3 interpreter found, install python3 with apt and re-run.

Download errors

"Prebuilt agent binary missing"

A warning that the release has no ready-made agent for this CPU, so the installer will build it from source, which needs the Go toolchain. On x86_64 and aarch64 this should not happen; re-run the installer to download the release again.

"Database migrations failed"

The installer aborts rather than leave the panel on a broken database. Read the end of /var/log/vpanel-install.log for the reason, fix it, and re-run.

Installed, but the panel does not open

• Use the full address printed at the end, including the secret path: https://YOUR_SERVER_IP:2711/<secret>/login/. Lost it? Run sudo vinzapanel --mode info.
• The certificate is self-signed, so the browser warns once. Choose Advanced → Proceed.
• The installer opens port 2711 in UFW, but your cloud provider may have its own firewall or security group. Allow TCP 2711 there too.
• Check that the services are running: systemctl status vinza-agent vinza-panel. See Service Recovery.