Skip to content

Troubleshooting: Proxmox

Error code Where it shows Cause Fix
PROVIDER_INVALID_CONFIG create/update/test SSRF guard: non-HTTPS scheme, 0.0.0.0, link-local/metadata IP (169.254.x.x), ::1, bad hostname. Use an https endpoint with a routable IP or DNS name; private LAN ranges are allowed by default.
PROVIDER_AUTH_FAILED (PC-PVE-003) test (auth_valid), rotation, tasks Token id/secret wrong, token deleted, or --privsep 1 token without its own ACLs. Re-check pveum user token list pterocloud@pve; rotate via Rotate Credentials (validate-first).
PROVIDER_PERMISSION_DENIED test steps, sync logs, tasks Token lacks a privilege the operation needs. Grant per permissions; the test's warnings name the missing privilege.
TLS_UNTRUSTED test (api_reachable) Self-signed cert under system_ca, or wrong/expired CA under custom_ca. Switch to pinned_fingerprint (bootstrap capture) or supply the correct CA PEM.
TLS_FINGERPRINT_MISMATCH test, tasks PVE certificate/key changed after the pin was captured. Verify the change was expected, then re-capture (clear the fingerprint and test again).
PROVIDER_UNAVAILABLE test, tasks, sync Endpoint unreachable, connection error, HTTP 5xx, or the connection is disabled. Check network/firewall to tcp/8006; is PVE up? Re-enable a disabled connection.
PROVIDER_TIMEOUT test, tasks A single HTTP call exceeded the 15 s timeout. Overloaded PVE API; retry later or raise the timeout.
PROVIDER_READ_ONLY power actions, rotation Connection has read_only set. Unset it if mutations should be allowed.
PROVIDER_CONFLICT imports Node/VM already mapped. Nothing to do — the mapping exists.
PROVIDER_NODE_NOT_IMPORTED VM import The VM's node has no hypervisor row. Import the node first.
PROVIDER_RESOURCE_NOT_FOUND imports, monitor VMID/node unknown to the provider. The VM was deleted/moved — check the orphan view.
PROVIDER_HAS_DEPENDENCIES delete Hypervisors/instances still mapped. Migrate/delete dependencies, or disable instead.
PROXMOX_TASK_FAILED (PC-PVE-005) task error The PVE task stopped with a bad exit status. The task error carries the exit status; check the PVE task log.
PROVIDER_TASK_TIMEOUT task error UPID still running after the monitoring budget. Inspect the PVE task; the instance is reconciled afterwards — never assumed.

First look

php artisan pterocloud:health
php artisan pterocloud:diagnose:provider <provider_uuid> --json
php artisan pterocloud:proxmox:test <provider_uuid>

pterocloud:health prints the Providers block (name/status, version, nodes online, last sync, pending provider tasks) for a fleet-level first look.

Common gotchas

  • Pasted URL as endpoint — a pasted URL is stripped to host+port for you; supplying a bare host is fine.
  • Read-only token + power action — the connection connects but power actions are rejected; check read_only and VM.PowerMgmt.
  • Cluster vs standalone — the cluster name is null on a standalone node. That is expected, not an error.