Errors

A failed call does not throw

When Proxmox VE refuses a call (a wrong parameter, a missing privilege, a VM that does not exist), the generated cmdlets do not throw an exception. They return a PveResponse like any other, with the outcome in its properties:

$r = Get-PveNodesQemuConfig -Node pve01 -Vmid 999

$r.IsSuccessStatusCode   # False
$r.StatusCode            # 500
$r.ReasonPhrase          # the reason given by Proxmox VE

try/catch and -ErrorAction Stop do not see these failures. A script that ignores IsSuccessStatusCode carries on with an empty Response.

`StatusCode`	Meaning
`200`	Success.
`400`	A parameter is missing or invalid; `ReasonPhrase` usually starts with `Parameter verification failed`.
`401`	Not authenticated: wrong or revoked token, expired ticket. `ReasonPhrase` is `Authentication failed!`.
`403`	Authenticated, but without the privilege the endpoint requires.
`500`	The operation failed on the server: the object does not exist, it is locked… `ReasonPhrase` says why, e.g. `Configuration file 'nodes/pve01/qemu-server/999.conf' does not exist`.
`-1`	No answer from the server: network, DNS, certificate. `ReasonPhrase` has the error of the connection.

Stop on errors

For scripts that must stop at the first failure, check every call. A small function keeps it short:

function Assert-PveSuccess {
    param([Parameter(ValueFromPipeline)] $Response)
    process {
        if (-not $Response.IsSuccessStatusCode) {
            throw "$($Response.Method) $($Response.RequestResource): $($Response.StatusCode) $($Response.ReasonPhrase)"
        }
        $Response
    }
}

$config = Get-PveNodesQemuConfig -Node pve01 -Vmid 100 | Assert-PveSuccess
$config.Response.data.memory

The message names the method and the path that failed, so the log of a scheduled job says which call broke.

What does throw

A few things do throw a PowerShell exception, because the script cannot go on without them:

Connect-PveCluster: no reachable host (Host not valid), wrong user or password, missing second factor: see Connection.
Any cmdlet called before Connect-PveCluster: No PveTicket - Cluster Connect missing?.
Get-PveTaskIsRunning, Get-PveTaskExitStatus and the Wait- functions when the status of the task cannot be read: see Tasks.
Parameter errors caught by PowerShell before the call: a missing mandatory parameter, a value outside the allowed ones, a [bool] without a value.

The functions that act on a selection of guests (Start-PveGuest, New-PveGuestSnapshot…) write a non-terminating error when nothing matches (VM/CT '…' not found!), and Reset-PveGuest writes one for each container it skips. When the list of the guests itself cannot be read (a missing privilege, a node that does not answer) the error is Cannot read the VM/CT of the cluster (<status>): <reason>, not “not found”. -ErrorAction Stop turns them into exceptions.