Troubleshooting

Logging

The client logs through Microsoft.Extensions.Logging. Give it a logger factory to see what it sends and receives:

using Microsoft.Extensions.Logging;

client.LoggerFactory = LoggerFactory.Create(builder => builder.AddConsole()
                                                              .SetMinimumLevel(LogLevel.Debug));

Level	What is logged
Debug	Method and URL of every request, the parameters of the requests that change something, then status code, reason and duration of the response
Trace	Also the JSON of every response
Error	The exception of a request that could not be completed (connection, certificate, timeout)

Compare the URL and the parameters with the endpoint in the Proxmox VE API viewer: most problems are a parameter with the wrong name or value.

In the list of parameters, those whose name contains password, token, ticket or otp are logged as ****. Other values, and the query string in the URL of a GET or DELETE request, are logged as they are: check the output before you share it.

In an application with dependency injection, pass the ILoggerFactory of the host instead of creating one.

Without a logger

Every call returns a Result, and the last one is also in client.LastResult. The event RequestCompleted is raised after every request, successful or not:

client.RequestCompleted += (_, result) =>
    Console.WriteLine($"{result.MethodType} {result.RequestResource} "
                      + $"{(int)result.StatusCode} {result.ReasonPhrase} {result.Duration.TotalMilliseconds:0} ms");

Status codes

A failed call does not throw: it returns a Result with IsSuccessStatusCode false. What the status code means:

Status	Meaning	What to do
400	Proxmox VE refused the parameters. ResponseInError is true and GetError() lists each parameter with its problem	Fix the parameter named in the error
401	The token or the ticket was refused: the token is wrong or revoked, or the ticket is older than two hours	Check the token, or log in again
403	Authenticated, but without the privilege the endpoint requires on that path	Check the roles of the user and, with privilege separation, of the token: Permissions
408	The request ran out of time: the Timeout of the client, or the one of HttpClient	Check that the node answers; raise Timeout if the endpoint is slow
500	Either Proxmox VE could not do what was asked (the reason is in ReasonPhrase, for example a VM id that does not exist), or the request never reached the node: name not resolved, connection refused, certificate refused	Read ReasonPhrase; for a certificate see Connection
502	The answer is not JSON: something that is not the Proxmox VE API answered. ReasonPhrase shows the start of what it sent	Check host and port, and proxies in between

More in Errors.

RuntimeBinderException reading Response.data

Response is dynamic: reading a member that is not there fails at run time, not when compiling. It happens most often when the call failed and the code reads its data anyway. Check IsSuccessStatusCode first, and compare the member names with the Returns section of the endpoint in the API viewer. To get typed data instead, see Results.

PveAuthenticationException: missing two-factor authentication

The user has two-factor authentication and LoginAsync was called without the second factor: see Connection. An API token needs none.

An empty list

A list that comes back empty with status 200 may mean an account without privileges: Proxmox VE leaves out what the caller may not see instead of returning an error. See Permissions.

The call succeeded but nothing changed

Starting a VM, a clone, a backup or a snapshot only starts a task: the successful Result says the task was accepted, not that it ended well. Wait for the task and read its exit status: see Tasks.

Reporting a problem

Open an issue with:

• the version of the package and of .NET (dotnet --version)
• the Proxmox VE version: (await client.Version.Version()).Response.data.version
• the code of the call and the Debug log of the request, without tokens or passwords