Cause. The controller has no backup repository, so it has no backup points to list, take or restore. The repository is the directory the controller writes its backups into, and that other backup software can write into too (one folder per virtual machine and backup, with a manifest and one raw image per disk).
Remedy.
Set the directory: kyvernon backup settings set --repository /srv/backup-repo, or in the console under backup settings. The setting verify_repository in the section [backup] of the controller configuration is the default.
With more than one controller, use shared storage mounted at the same path on each.
Check the result: kyvernon backup repository.
error.backup.repository_unusable
Text in the console
The repository {repository} cannot be created or written on this controller.
Meaning for API clients
The repository directory cannot be created or written on this controller.
Cause. During a backup the controller reads each disk over the export the host opens for it. The controller reached neither the export's socket on its own machine nor the export's address over the network. Without remote_exports in the section [backup], exports are local sockets on the host, which only a controller on the same machine reaches.
Remedy.
For a controller on another machine than the host, set remote_exports = true in the section [backup] of the controller configuration and restart it; exports then use TCP with TLS and the host's certificate fingerprint.
Check that the host's export port can be reached from the controller.
Start the backup again: kyvernon vm backup <vm>.
error.backup.change_tracking
Text in the console
Change tracking could not be turned on for {vm}.
Meaning for API clients
Change tracking could not be turned on for the virtual machine before its first backup.
Cause. A backup reads only the changed areas of a disk, and needs change tracking on the virtual machine. The controller turns it on before the first backup, and that change failed.
Remedy.
Look at the failed reconfiguration task of the virtual machine for its reason: kyvernon tasks list --entity <vm>.
Turn change tracking on yourself in the virtual machine settings, then start the backup again.
Cause. A restore in place replaces the disks of the virtual machine the backup point came from. That is only done while the virtual machine is powered off.
Remedy.
Shut the guest down and power the virtual machine off: kyvernon vm shutdown <vm>.
Start the restore again: kyvernon backup restore-point <point> --in-place.
To keep the virtual machine running, restore to a new virtual machine instead (without --in-place).
error.backup.verify_failed
Text in the console
The restore finished, but backup point {point} did not pass the verification in quarantine.
Meaning for API clients
The restore finished, but the verification of the backup point in quarantine failed.
Cause. The restore finished, but the verification asked for with it failed: a separate virtual machine made from the backup point on the quarantine network did not boot an operating system, did not get an address, or did not answer on a requested port in time. The restored virtual machine stays as it is.
Remedy.
Read the verification result in the task, or the report: kyvernon backup verification report. The reason names the evidence that was missing.
Check the restored virtual machine before you use it, or restore an older backup point.
For a guest that boots slowly, verify again with a longer timeout.
error.backup.controller_running
Text in the console
A backup of the controller state is already running.
Meaning for API clients
A backup of the controller state is already running.
Cause. The folder for the archives of the controller state cannot be created, or the controller service may not write in it.
Remedy.
Check the folder set as controller_target in the section [backup] of the controller configuration (default: controller-backups next to the state directory).
Give the controller service write access, or choose another folder and restart the controller.
error.backup.controller_changed
Text in the console
{file} changed while it was archived. Run the backup again.
Meaning for API clients
A file of the state directory changed while it was archived.
Cause. A file of the state directory other than the two stores changed while the archive was written, so the archive would not hold the file as it was checked. The stores are copied from one consistent read and are not affected.
Remedy.
Start the backup again: kyvernon system controller-backup --wait.
When it keeps failing on the same file, look at what writes to it (the file is named in the error).
error.backup.controller_unreadable
Text in the console
The archive of the controller state does not read back as written; it was not kept.
Meaning for API clients
The archive that was written does not read back as written.
Cause. After writing, the controller reads every archive back and checks each file against its checksum. This archive did not read back as written, so it was removed and the older archives stay. The usual causes are a full or failing disk under the archive folder.
Remedy.
Check the free space and the health of the disk under the archive folder.
Start the backup again: kyvernon system controller-backup --wait.
error.backup.controller_unavailable
Text in the console
This controller keeps its state in memory; there is nothing to archive.
Meaning for API clients
This controller keeps its state in memory; there is nothing to archive.
Cause. A backup point is restored with the configuration of its virtual machine (processors, memory, network adapters), and that virtual machine no longer exists.
Remedy.
Create a virtual machine with the configuration you need, then restore the disks of the backup point into it with the backup software.
Keep virtual machines whose backups you may need, or keep a template of their configuration.