-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Ferrum proxies every request live to the target Proxmox host — a 502 from Ferrum usually means the upstream PVE/PBS host itself returned an error or couldn't be reached. Check, in order:
-
Reachability — can the machine running Ferrum reach
host:port(default8006for PVE,8007for PBS)? Firewalls between Ferrum and the target are the most common cause. - TLS — Proxmox ships a self-signed certificate by default. If you haven't replaced it with one from a real CA, leave TLS insecure checked on the connection (the "Verify TLS certificate" checkbox, unchecked by default) — otherwise every request fails certificate verification.
-
Credentials — an API token needs the
user@realm!tokenidformat (e.g.root@pam!ferrum) with "Privilege Separation" off if you want it to inherit the user's full permissions, or a matching set of ACLs on the token itself otherwise. A username/password connection needs an account that can actually log in to the PVE API (not just SSH). -
A genuinely standalone node — some cluster-scoped endpoints (
/cluster/config/nodes,/cluster/status) error by design on a non-clustered host, since there's nocorosync.confto read. Ferrum treats that as "not part of a cluster" rather than an error on pages that expect it (Cluster & SDN's Members list, for one) — if you see a real error card instead, that's worth reporting.
A few node-level endpoints (the systemd journal, node certificates, DNS, /etc/hosts, time sync) are admin-only by design, since they can expose more of the host than a non-admin operator should see. If you're signed in as a non-admin user, that's expected — sign in as an admin, or have one granted to your account from Users.
See AI Assistant and MCP — the built-in Needle 2 provider has its own section, including a specific fix for it getting OOM-killed on small ARM boards (FERRUM_NEEDLE_MAX_TOOLS).
If a different configured provider (OpenAI, Ollama, ...) fails, use the "Test" button next to it under Settings > AI Providers — it reports whether Ferrum could reach the endpoint and, if the provider supports it, which models it discovered.
The console and shell both go over a WebSocket that Ferrum proxies to the target host's own vncproxy/termproxy ticket. If it fails immediately:
- Check that nothing between your browser and Ferrum strips WebSocket upgrade headers (some reverse proxy configs need an explicit
Upgrade/Connectionheader pass-through). - A shell session failing with a PVE-side error (e.g.
/bin/loginexiting non-zero) is usually a problem on the target host — PAM/root-login configuration, a locked account, or a container without a usable shell — not something Ferrum's proxying can fix. Check the equivalent shell/console session directly from the Proxmox web UI to confirm it's not Ferrum-specific.
There's no "forgot password" flow yet — an existing admin resets another user's password from Users. If no admin account is usable at all, the account records live in the configured database (SQLite file or Postgres) and can be edited there directly as a last resort; back up the database file first.
Open an issue with: your Ferrum version (ferrum -version, or the footer in Settings), how you deployed it (Docker/systemd/Windows service/source), and — for anything connection-related — the Proxmox VE/PBS version you're connecting to.