Skip to main content

​
Overview

This page covers the most common operator-side issues when running backups and restores with Ironcore Backup Solution. Use the categorised accordions below to find the matching error, then walk through the diagnostic steps. Escalate to your administrator for issues that touch datastore provisioning, replication, or service-wide configuration.
Diagnostic Inputs
  • The task UPID (visible in the Task Browser or returned by the CLI)
  • The exact failure message from the task log
  • The Workload identifier (VM, container, or host ID)
  • Time of failure (timezone is shown in the task detail panel)

​
Backup Failures

`source not reachable`

The backup client could not contact the workload to be backed up.Diagnostic steps:
  1. Confirm the workload is running. For VMs, check Compute > Instances.
  2. For host backups, confirm the backup client is installed and the host can reach the backup server on TCP/8007.
  3. Inspect the task log for the precise error — DNS failure, connection refused, or authentication.
Resolution: start the workload, restore network connectivity, or contact your administrator if the backup server is unreachable.
The target datastore is full.Diagnostic steps:
  1. Open the Dashboard. Datastore usage is shown on the main page.
  2. Check pruning history — has the prune job run on schedule?
  3. Confirm with your administrator whether the datastore needs expansion.
Resolution: prune older snapshots if your retention allows, or wait for your administrator to expand the datastore.
The user or API token does not have permission on the target datastore or namespace.Diagnostic steps:
  1. Confirm the datastore and namespace shown in the task.
  2. Open Access Control to view your assigned roles on that datastore.
  3. The required role for backup operations is Datastore.Backup or Datastore.Admin.
Resolution: request the appropriate role from your administrator.
The job references an encryption key that is not loaded on the client.Diagnostic steps:
  1. Confirm the keyfile path on the backup client.
  2. Open Encryption Keys to verify the project key is registered.
Resolution: request the project’s encryption key file from your administrator. Never share encryption keys in clear text.
Another backup or snapshot operation is running on the same source.Diagnostic steps:
  1. Open the Task Browser and filter by the workload ID.
  2. Wait for the in-progress task to complete.
Resolution: avoid scheduling overlapping backup jobs on the same source.

​
Restore Failures

The target host or storage is full, read-only, or unavailable.Diagnostic steps:
  1. Confirm storage backend health from Compute > Storage.
  2. Try restoring to a different storage backend or compute host.
A chunk referenced by the snapshot manifest is absent from the datastore.Resolution: this indicates a datastore integrity issue. Stop the restore immediately and contact your administrator. Run a verification job on the snapshot to confirm scope. Try restoring from an earlier snapshot or from the Backup site replica.
The encryption key on the client does not match the key used for the snapshot.Diagnostic steps:
  1. Confirm the key file used. Each project usually has one primary key.
  2. Check the snapshot detail for the Key fingerprint and compare with your key fingerprint.
Resolution: use the correct key file or request access from your administrator.
The restored disk image is intact but the VM fails to boot.Common causes:
  • Storage backend type mismatch (for example, SATA vs. SCSI controller)
  • Missing virtio drivers in the guest OS
  • Boot order set incorrectly on the new VM
Resolution: open the VM serial console, inspect the boot loader, and adjust the VM definition. Try matching the source VM’s storage controller.
Background restore has slowed due to network or target storage contention.Diagnostic steps:
  1. Check Statistics for current throughput.
  2. Look at target storage IO saturation.
The guest stays usable for normal IO; only the background fill is delayed. If this is unacceptable, fall back to a standard VM restore with the guest powered off.

​
Throughput Issues

Common causes:
  • Bandwidth limit on the datastore or job
  • High source IO (VM under heavy load)
  • Network saturation between client and backup server
  • Cold caches — first backup of a new source is slower than subsequent runs
Diagnostic steps:
  1. Open Statistics for the job and check effective transfer rate.
  2. Check the deduplication hit rate. Below 30 percent on incremental runs indicates the source has changed substantially.
  3. Look at the backup server’s CPU and disk utilisation (admin view).
Restore reads many chunks and writes to the target — often more IO-bound than backup. Network and target storage write speed determine the ceiling.Resolution: choose a faster target storage backend or restore at a time when storage IO is less saturated.

​
Encryption and Key Errors

A key is loaded but it does not match the one used at backup time.Resolution: identify the correct key by snapshot Key fingerprint and obtain it from your administrator.
The QR code scan failed or the hex blocks are not entered cleanly.Resolution: re-scan with better lighting, or type the printed hex blocks manually. The paperkey checksum will reject malformed input.
A snapshot was created without enrolling it in the project master key.Resolution: future backups will encrypt under the master key once enrolled. Existing un-enrolled snapshots remain protected by their own key but cannot be recovered without that key.

​
Common Errors Quick Reference

ErrorCauseFirst Action
source not reachableWorkload offline or networking issueVerify workload is running
permission deniedMissing datastore/namespace roleRequest role from administrator
no space left on datastoreDatastore fullPrune or request expansion
chunk not foundDatastore integrity issueVerify snapshot, contact administrator
decryption failedWrong encryption keyLoad the correct key file
encryption key not foundKey file missing on clientRequest key from administrator
task cancelledOperator cancellation or worker restartRe-run the task
connection refusedBackup server unreachableVerify TCP/8007 connectivity

​
Escalating to Your Administrator

Provide your administrator with the following:
InformationSource
Task UPIDTask Browser or CLI output
Workload identifierAffected VM, container, or host ID
Project nameTop-right of the Dashboard
Exact failure textTask log
Time of failureTask detail panel
FrequencyOne-off, recurring, or escalating

​
Next Steps

Monitoring Jobs

Track tasks and verification reports

Backup Solution Admin

Datastore, replication, and access control configuration (administrators)

Polystack Support

Open a support ticket with Polystack Technologies

How It Works

Conceptual overview to understand task internals