Troubleshooting

The Issues page

A single failing call does not stop the report. A node that does not answer, a storage with a broken RRD file, a privilege the token does not have: the call is recorded, that part of the report stays empty, and everything else is written.

The failures are listed in an Issues section: the second sheet in Excel, right after Summary and first in its Contents; issues.html in HTML, second in the sidebar; issues.json in JSON. The section exists only when something failed — if it is not there, every call succeeded.

Column	Content
Severity	Warning
Section	Where the failure happened, e.g. RRD Storage, Firewall Log, Cluster. Links to the page of the resource concerned — node, VM, container or section
Message	HTTP status code, the error returned by Proxmox VE and the failing call: 500 got wrong time resolution (60 != 1800) — Get /nodes/pve01/storage/local-ceph/rrddata
Timestamp	When the failure was recorded

A 501 Not Implemented is not listed: it means the endpoint does not exist on that Proxmox VE version, so there is nothing to fix.

A few calls are needed to start at all — the list of resources and guests, and with Cluster.Include the cluster status and the Proxmox VE version. If one of them fails, the tool stops with ERROR: … and writes no report.

What the most common messages mean:

• 403 Permission check failed: the token lacks a privilege. The message names the path and the privilege; see Permissions.
• 500, 595 or 596 on a node: the node is offline or unreachable from the node you connected to.
• 500 on …/rrddata: the RRD file of that resource is damaged. The rest of the report is fine.
• Timeouts: raise ApiTimeout, or lower MaxParallelRequests — see Performance.

An empty section is not always an error

Proxmox VE does not answer with an error when a token may see only part of the cluster: it leaves out what the token cannot see. A guest without VM.Audit is simply missing from the report, with nothing on the Issues page. If a report looks too small, check the privileges — see Permissions.

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.

--debug also shows which calls are slow: every call is logged with its duration.