Troubleshooting

Connection

Start with cv4pve-cli config verify: it connects with the current context and prints the Proxmox VE version, or the reason it could not.

Message	Meaning
The SSL connection could not be established	The certificate of the node is not trusted, usually the self-signed one of a new node. See Certificate.
No reachable hosts found	No node in --host answered on its port: wrong name, address or port, or a firewall.
Authentication failed	Wrong token or password, or a realm missing from the username (admin is looked up in pam, not pve).
Missing Two Factor Authentication (TFA)	The account has two-factor authentication: use an API token.
No context configured. Run 'config add' first.	There is no current context: add one with config add: see Contexts.

Git Bash on Windows

Git Bash (MSYS) rewrites arguments that start with / into Windows paths before cv4pve-cli sees them: /version arrives as C:/Program Files/Git/version. cv4pve-cli recognises it and stops:

Error: 'C:/Program Files/Git/version' is not an API path: Git Bash turned it into a Windows path. Run the command with MSYS_NO_PATHCONV=1.

Turn the rewriting off for the command, or for the whole session:

MSYS_NO_PATHCONV=1 cv4pve-cli api get /version
export MSYS_NO_PATHCONV=1

PowerShell, cmd, WSL, Linux and macOS are not affected.

API calls

When Proxmox VE refuses a call, cv4pve-cli prints its message, the call it sent and, for an alias, what the alias runs. If the parameter refused is written in the alias itself, the message says so: the alias is wrong, not your command.

$ cv4pve-cli get vm status pve01 100 --foo 1
Error: Proxmox VE refused the call (HTTP 400):
  Parameter verification failed.
  foo : property is not defined in schema and the schema does not allow additional properties

Call:  GET /nodes/pve01/qemu/100/status/current --foo 1
Alias: 'get vm status' runs 'get /nodes/{node}/qemu/{vmid}/status/current'
Parameters it accepts: cv4pve-cli api usage /nodes/pve01/qemu/100/status/current get -v

The first lines are those of Proxmox VE:

Message	Meaning
Permission check failed (/vms/100, VM.PowerMgmt)	The account lacks that privilege on that path: see Permissions.
Method 'GET /nodex' not implemented	The path does not exist, or does not accept that method. api ls and api usage show what it does accept: see API calls.
hostname lookup 'pve99' failed	The node name in the path is not a node of the cluster.
Configuration file 'nodes/pve01/qemu-server/100.conf' does not exist	No VM with that ID on that node. --guest finds the node for you: see Aliases.
Parameter verification failed.	A parameter is unknown, missing or has a wrong value; the next lines name it. api usage … -v lists what the call accepts.
Error: missing arguments: {node}, {vmid}	An alias was called without all its arguments; the next line shows its usage.
Error: '…' changes the cluster: add --yes to confirm.	The alias needs --yes: see Aliases.

An empty answer is not always an error

Proxmox VE leaves out of a list what the account may not see, and answers normally. If top or get vms shows fewer guests than you expect, check the privileges of the token.

Every error goes to standard error with an exit code other than 0: see Scripting.

Debug output

Two options, not listed in --help, show what the tool is doing. They work before or after the command:

Option	What it does
--debug	On an error, prints the exception type and stack trace after the ERROR: line.Also logs each Proxmox VE API call: method, URL, status and duration, and the parameters of calls that change data; passwords, tokens and tickets are masked.
--log-level	Trace, Debug, Information, Warning (default),Error or Critical; overrides --debug.Trace also logs the full API responses; they contain details of your cluster, so review the output before sharing it.

When you report a problem, attach the output of the failing command run with --debug.

cv4pve-cli prints errors as Error: …; with --debug an error that is not an answer of Proxmox VE (a node unreachable, wrong credentials) is followed by its stack trace. When a call fails before an answer (a node that drops the connection, an answer that is not JSON), the error is logged as fail: with its stack trace, even without --debug. To see the full JSON answer of a call that succeeds, add -v to the api command.