> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Backup Solution Troubleshooting

> Resolve common Ironcore Backup Solution issues — failed backups, restore errors, encryption key access problems, and slow throughput.

## 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.

<Note>
  **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)
</Note>

***

## Backup Failures

<AccordionGroup>
  <Accordion title="`source not reachable`" icon="server" defaultOpen>
    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.
  </Accordion>

  <Accordion title="`no space left on datastore`" icon="hard-drive">
    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.
  </Accordion>

  <Accordion title="`permission denied`" icon="lock">
    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.
  </Accordion>

  <Accordion title="`encryption key not found`" icon="key">
    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.
  </Accordion>

  <Accordion title="`source busy` or `snapshot in progress`" icon="hourglass">
    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.
  </Accordion>
</AccordionGroup>

***

## Restore Failures

<AccordionGroup>
  <Accordion title="`destination not writable`" icon="hard-drive">
    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.
  </Accordion>

  <Accordion title="`chunk not found`" icon="search">
    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.
  </Accordion>

  <Accordion title="`decryption failed`" icon="lock">
    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.
  </Accordion>

  <Accordion title="Restored VM does not boot" icon="alert-triangle">
    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.
  </Accordion>

  <Accordion title="Live-restore stays in `restoring` indefinitely" icon="clock">
    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.
  </Accordion>
</AccordionGroup>

***

## Throughput Issues

<AccordionGroup>
  <Accordion title="Backups taking longer than expected" icon="gauge">
    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).
  </Accordion>

  <Accordion title="Restore is slower than backup" icon="hourglass">
    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.
  </Accordion>
</AccordionGroup>

***

## Encryption and Key Errors

<AccordionGroup>
  <Accordion title="`fingerprint mismatch`" icon="key">
    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.
  </Accordion>

  <Accordion title="Paperkey scan does not produce a usable key" icon="qr-code">
    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.
  </Accordion>

  <Accordion title="Master key required but not configured" icon="alert-triangle">
    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.
  </Accordion>
</AccordionGroup>

***

## Common Errors Quick Reference

| Error                        | Cause                                   | First Action                           |
| ---------------------------- | --------------------------------------- | -------------------------------------- |
| `source not reachable`       | Workload offline or networking issue    | Verify workload is running             |
| `permission denied`          | Missing datastore/namespace role        | Request role from administrator        |
| `no space left on datastore` | Datastore full                          | Prune or request expansion             |
| `chunk not found`            | Datastore integrity issue               | Verify snapshot, contact administrator |
| `decryption failed`          | Wrong encryption key                    | Load the correct key file              |
| `encryption key not found`   | Key file missing on client              | Request key from administrator         |
| `task cancelled`             | Operator cancellation or worker restart | Re-run the task                        |
| `connection refused`         | Backup server unreachable               | Verify TCP/8007 connectivity           |

***

## Escalating to Your Administrator

Provide your administrator with the following:

| Information         | Source                             |
| ------------------- | ---------------------------------- |
| Task UPID           | Task Browser or CLI output         |
| Workload identifier | Affected VM, container, or host ID |
| Project name        | Top-right of the Dashboard         |
| Exact failure text  | Task log                           |
| Time of failure     | Task detail panel                  |
| Frequency           | One-off, recurring, or escalating  |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Monitoring Jobs" icon="activity" href="/services/ironcore-backup/user-guide/monitoring-jobs" color="#bf9667">
    Track tasks and verification reports
  </Card>

  <Card title="Backup Solution Admin" icon="shield-check" href="/services/ironcore-backup/admin-guide" color="#bf9667">
    Datastore, replication, and access control configuration (administrators)
  </Card>

  <Card title="Polystack Support" icon="headphones" href="mailto:support@polystack.tech" color="#bf9667">
    Open a support ticket with Polystack Technologies
  </Card>

  <Card title="How It Works" icon="info" href="/services/ironcore-backup/user-guide/how-it-works" color="#bf9667">
    Conceptual overview to understand task internals
  </Card>
</CardGroup>