Troubleshooting

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 the command run on each node over SSH and how long it took.
`--log-level`	`Trace`, `Debug`, `Information`, `Warning` (default),`Error` or `Critical`; overrides `--debug`.

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

Common errors

Every error ends the run with exit code 1. Errors in the options are printed with the help of the command, the others as ERROR: <message> before anything is backed up.

An error on one node is printed as ERROR [node]: <message>, and the run goes on with the other nodes. At the end the tool prints the nodes that failed and applies no retention (see When a run fails):

ERROR [pve02]: Connection has timed out.
Create config: 2026-09-29-03-00-01/pve01-config.tar.gz
ERROR: Backup failed for 1 of 2 node(s): pve02. Retention not applied.

Message	Printed as	Cause
`Option '--username' is required!`	`ERROR:`	`--username` is missing; it is needed with a key too.
`Option '--password' is required when using '--username' without a private key!`	`ERROR:`	Neither a password nor a key was given.
`Option … whit value '…' is not a valid file!`	With the help	The folder in `--directory-work` does not exist (the message says “file” for folders too). Create it first.
`Password file not found: …`	`ERROR:`	The file after `--password=file:` does not exist.
`Invalid IPv6 format, missing ']': …` / `Invalid port after ']' in: …`	`ERROR:`	An entry of `--host` in brackets is not `[address]` or `[address]:port`.
`Connection has timed out.`	`ERROR [node]:`	The node did not answer within `--timeout` seconds (30 by default): wrong address or port, node down, firewall.
`Permission denied (password).` / `Permission denied (publickey).`	`ERROR [node]:`	The node refused the user and the password, or the key.
`Path must not contain single quotes: … (Parameter 'value')`	`ERROR [node]:`	A path in `--paths` contains `'`, which the tool does not accept. Checked before connecting, so every node reports it.
`[node] tar failed (exit N): …`	`ERROR [node]:`	`tar` on the node exited with code 2 or more; its own error message follows.

The archive is smaller than expected

Every path tar leaves out is printed as a warning, and the run still ends with exit code 0:

warn: Corsinvest.ProxmoxVE.NodeProtect.Api.ProtectEngine[0]
      [pve01] tar: /etc/doesnotexist: Warning: Cannot stat: No such file or directory

In a scheduled run, look for these lines in its log. To check an archive, list it and look for what you expected:

tar -tzf pve01-config.tar.gz | grep -E 'config.db|network/interfaces'

The usual causes: a typo in --paths, a user other than root (Which account), or a path on another file system, such as /etc/pve inside /etc/. (why).

Git Bash on Windows

Git Bash rewrites an argument that starts with / into a Windows path, so --paths='/etc/.' reaches the tool as C:/Program Files/Git/etc/.. No such path exists on the node: tar prints the warning above, the archives are empty and the run still ends with exit code 0.

Directory Node to archive:
C:/Program Files/Git/etc/hostname
warn: Corsinvest.ProxmoxVE.NodeProtect.Api.ProtectEngine[0]
      [pve01] tar: C\:/Program Files/Git/etc/hostname: Warning: Cannot stat: No such file or directory

Turn the conversion off for the command:

MSYS_NO_PATHCONV=1 cv4pve-node-protect --host=pve01 --username=root --private-key-file=key backup \
    --keep=7 --paths='/etc/.;/etc/pve/.' --directory-work=C:/backup/node-protect

PowerShell and cmd do not rewrite the paths. Paths in an options file are not rewritten either.