EN Troubleshooting

Troubleshooting

中文版：常见报错

The panel signs in, but the VM and storage lists are empty

Open Settings → Environment self-check first. A token created in the Proxmox web UI has privilege separation enabled by default, and such a token starts with no permissions at all. Reads that need privileges return 403, while endpoints like /storage return 200 with an empty array without reporting an error, so the panel can only render an empty list and it looks like the panel is broken.

The self-check asks Proxmox for the token's effective permissions (/access/permissions) and prints the commands to fix it:

pveum acl modify / --tokens 'root@pam!panel' --roles PVEVMAdmin
pveum acl modify / --tokens 'root@pam!panel' --roles PVEDatastoreUser
pveum acl modify / --tokens 'root@pam!panel' --roles PVEAuditor   # node metrics need Sys.Audit

The tell-tale sign is privsep = 1 in pveum token list. Details in Token and permissions.

The service will not start: how to read the logs

systemctl status proxcenter --no-pager -l
journalctl -u proxcenter -n 50 --no-pager
tail -n 50 logs/panel.log

Log line	Meaning
"panel startup was rejected"	A .env problem; the sentence after it names the key to fix, usually SECRET_KEY or ADMIN_PASSWORD
Access denied for user	Wrong database account or grants (re-run with --db-* to rewrite .env)
Can't connect to MySQL	The database is not running (locally: systemctl status mariadb)
Address already in use	Port 8080 is taken; change it with --port
ModuleNotFoundError / cannot find app	Dependencies are incomplete; re-run without --skip-deps

An unreachable Proxmox does not stop the panel from starting, it only leaves a warning in the log. That is deliberate: if it refused to start, one bad configuration would lock you out of the UI you need to fix it with.

Docker: the container will not start, or keeps restarting

Almost always the database password. The MySQL container initialises its credentials only when its data directory is empty, so changing MYSQL_ROOT_PASSWORD or DB_PASSWORD after the first run leaves the panel authenticating with a password the database does not have:

docker compose logs panel | tail -30     # look for Access denied / Can't connect

Either start over (docker compose down -v && docker compose up -d, which wipes the data) or change the password in the database by hand with ALTER USER. Both are spelled out at the bottom of docker-compose.yml.

I changed a configuration value and nothing happened

Connection settings are resolved database first, then .env. If a different address was saved earlier, editing .env has no effect. Change it under Settings, or clear the stored record and restart:

DELETE FROM settings WHERE `key` = 'pve_connection';

The console

• Will not open: Proxmox does not allow an API token to access vncproxy. Add a PVE account and password under Settings, ideally a dedicated account with only PVEVMUser.
• Connects but stays black: cloud images do not write boot output to the graphical console. Templates built by the panel already add serial0 and vga: serial0; a hand-made template needs them added manually.
• Drops behind Nginx: the location /api/ block must carry proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade";, and proxy_read_timeout has to be raised, because the console is a long-lived connection.

Storage

no space left or a storage error while creating a VM: check which disk formats the target storage supports. LVM and ZFS only take raw; qcow2 needs dir, NFS or CIFS. The panel corrects the format automatically, but a full storage pool can only be fixed by using another pool.

The host-security pages read nothing

"Security baseline", "SSH login security" and "Port and process detection" read the logs and /proc of the host the panel runs on, plus any managed hosts added over SSH. Inside a container those paths belong to the container rather than the host, and the pages say so instead of showing an empty list. Mount the host paths read-only if you want them (the comments in docker-compose.yml describe how); the panel never writes to them.

After upgrading: the pages show data from a few minutes ago

"Port and process detection" and "Security baseline" do not read a stored record. They SSH into every host and run a probe, up to 45 seconds per host. So that nobody waits for that, the panel shows the previous result immediately and rescans in the background. The "collected at" timestamp at the top of the page tells you which run you are looking at.

All of this is expected:

• the page appears instantly while the timestamp is a few minutes old;
• until that background rescan finishes you are still looking at the previous result, and reopening or reloading once will pick up the new one;
• a stale result is used for at most 15 minutes; anything older is discarded and the request waits for a real scan.

To force a real scan right now, use "Rescan" in the page header, which bypasses the cache.

With many hosts a single scan still takes a while (16 hosts are probed concurrently, i.e. ceil(hosts / 16) batches). That concurrency is a backend constant, PROBE_CONCURRENCY (backend/app/baseline.py), not an .env option. Raise it if your fleet is far larger.

After upgrading: the target_guest warning in the log

给 audit_log 补 target_guest 失败：创建时间回填会退化成查不到

On the first start after an upgrade the panel adds a column and an index to the audit table (used to answer "when was this guest cloned?" quickly), and that needs ALTER on the database account. Missing it does not break anything: the only effect is that a cloned guest may show the inherited template time as its creation time. Grant it and restart:

GRANT ALTER ON proxcenter_panel.* TO 'proxcenter'@'localhost';

(Substitute your database name and account.)

After updating, the UI still looks old or is missing new features

The update finished and the version number changed, yet the UI looks the same and a newly added button is nowhere to be found. That usually means the frontend build did not follow: the backend code is current, the service runs, the page opens, and the UI is just serving the previous dist/.

The panel now reports this itself. Open Settings → Panel version and updates; a "frontend build and backend differ in version" notice is exactly that. Rebuild by hand:

cd /data/proxcenter        # your install directory
npm install                # dependencies may not have been synced across a skipped release
npm run build
sudo systemctl restart proxcenter

Since 0.2.3 deploy.sh checks the frontend dependencies on every run, and it returns in seconds when nothing changed. The "skipped a release, new dependency missing, build fails with a wall of Cannot find module" failure no longer happens, and a stale build is reported on the settings page together with the commands to fix it.