Troubleshooting
Common provider onboarding issues and how to fix them
Symptom-first fixes for the setup path in Get started. If you are blocked earlier in onboarding, start with the matching section below.
Agent not provisioned
Symptoms: Agent stays Unprovisioned, no green status, or operator pod not Running.
Confirm the agent VM is reachable
The public IPv4 you registered must match the VM running the install script. Outbound HTTPS and the WireGuard peering ports must not be blocked.
Re-run the install from the Provisioning tab
Open /infrastructure/agents → select the agent → Provisioning tab → copy the Installation command again and run it on the Ubuntu VM.
Check the operator on the agent VM
On the agent VM, run kubectl get pods -A and confirm the proxmox-operator pod is Running. Wrong Proxmox URL or API token is the most common cause. Verify with pvesh on the hypervisor and compare Proxmox API user and token.
More detail: Agents.
Platform offline or unreachable
Symptoms: Platform does not show online, or preflight fails platform_online / agent_online.
Agent must be provisioned first
Do not create a platform until the linked agent is provisioned with a green status. Finish Get started → Agent first.
Test connectivity from the agent VM
From the agent VM (not your laptop), curl the Proxmox endpoint you entered, for example curl -k https://192.168.1.100:8006/. If this fails, fix routing, firewall, or DNS before retrying.
Match endpoint URL and driver
Use the full URL including https:// and port 8006. Select driver Proxmox and link the correct agent.
More detail: Platforms & nodes.
Node name mismatch
Symptoms: VMs never appear on the expected host, node shows wrong inventory, or operator errors referencing unknown node.
The node name in NodeRings must exactly match Proxmox: same spelling, hyphens, and casing. Copy from the Proxmox datacenter tree (for example proxmox01-lab01-dev). Do not use a display label you invented in NodeRings.
On Proxmox, open Datacenter in the left tree and read the node name under your cluster. Update the node in NodeRings if it differs, or delete and re-add with the correct name.
Storage or backup errors
Symptoms: Clone fails, backup fails, or permission errors mentioning datastore.
- VM disk storage and Backup storage must be valid Proxmox storage IDs on that node (for example
local-lvm,local). - The Proxmox API token needs ACLs on each storage path, see Proxmox API user and token.
- Confirm free space on the pool in the Proxmox UI.
Preflight failures
Symptoms: Red cells on /infrastructure/preflight-check.
| Gate | What to check |
|---|---|
agent_online | Agent provisioned; platform linked to agent |
platform_online | Proxmox API reachable from agent; metrics flowing (pve_up=1) |
node_online | Node active, correct region, network attached, not in maintenance |
plan_physical_fit | Node has enough physical CPU, RAM, and disk for the plan |
plan_capacity | Sell headroom after overallocation, not the same as physical fit |
os_template | VM template registered on that node |
ip_available | Dual-stack IPAM with enough free addresses |
addons_created | Addons exist with billing type matching the plan |
Full gate definitions: Preflight Check.
Domain verification fails
DNS TXT or HTTPS file challenge did not validate. See Domain → Step-by-step. Wait for DNS propagation and retry.
Still stuck?
- Architecture and security model: How it works
- Agent install and peering: Agents
- Billing and payouts: Billing & Payouts