Backup Troubleshooting

No backup configuration available

Symptom: Manual backup fails with “No backup config available.”

Cause: No storage configuration exists for your organization, or no policy targets the device.

Fix:

Create a storage configuration if you haven’t already.
Create a backup policy that targets the device, or ensure at least one storage configuration exists in the organization (the system falls back to any available config).

Job stuck in Queued status

Symptom: A backup job stays in Queued and never starts.

Cause: The job was created but the agent hasn’t picked it up.

Fix:

Verify the target device is online (check the device list for connectivity status).
Confirm the Breeze agent is running on the device.
Check that Redis is operational — backup jobs are dispatched through the job queue.

If a manual backup request cannot be queued at all, Breeze now marks the job Failed immediately with the dispatch error instead of leaving it queued forever.

Job fails immediately

Symptom: Job moves to Failed status within seconds.

Cause: Typically a storage connectivity issue or permission error.

Fix:

Open the failed job to read the error message.
Test the storage configuration connectivity (click Refresh/Test on the config).
Verify storage credentials haven’t expired or been rotated.
Check that the agent has network access to the storage target.

Backup job fails with “backup helper exited unexpectedly”

Symptom: A backup job that was running normally suddenly fails, with an error mentioning the backup helper exiting unexpectedly — most often on a small or busy device during a large backup.

Cause: Under sustained load, the agent’s internal health check can time out and trigger an agent restart, which also stops any backup helper process that was in progress.

Fix: Re-run the backup — Breeze resumes from where it left off using its checkpoint journal instead of starting over. If this happens repeatedly on the same device, reduce load on it during the backup window or narrow the backup scope.

Backup waits for the backup component to report

Symptom: A backup or restore stays queued with a note naming the backup component, or a backup fails with “The backup was not started because the backup component on this device hasn’t reported which storage features it supports yet. If the device is online, update or reinstall the Breeze agent, then run the backup again.”

Cause: Each heartbeat reports which storage features the device’s backup helper supports. When the agent cannot ask the helper (not installed yet, crashed, timed out, unreadable output), it reports unknown rather than “no support”. A device that already reported support keeps its last known value; a device with no report yet waits — for up to 10 minutes — instead of being treated as an older helper. The agent retries the check after 1, 2 and 4 minutes, then every 5 minutes.

Fix: Usually none: the next successful check releases the work. If the message persists while the device is online, update or reinstall the Breeze agent on the device, then run the backup again.

Restore refused: “did not match its integrity record”

Symptom: A restore, verification or VM restore fails with This backup did not match its integrity record and cannot be read from storage.

Cause: The snapshot’s stored objects did not match its attestation when they were checked. Breeze will not read such a snapshot. See Integrity checks on restore.

Fix: Restore from a different snapshot. Investigate the storage target for tampering or corruption. If the message instead says the file list is being rebuilt from storage, wait a few minutes and run the restore again.

Deleting a backup destination fails

Symptom: Deleting a backup destination that has ever run a backup returns a server error.

Cause: Known issue in v0.120.0: a destination with job history cannot be deleted.

Fix: Stop using the destination instead of deleting it: reassign the policies that point at it, then disable it (PATCH /backup/configs/:id with "enabled": false).

Snapshot browse returns empty

Symptom: A snapshot exists but the file browser shows no contents.

Cause: The agent didn’t report file-level metadata during the backup, or the browsing index was pruned while the snapshot record remains.

Fix: This is expected for some backup types (e.g., system image or Hyper-V exports). File-level browsing is available for file-mode backups. For other types, restore the full snapshot to inspect contents.

Restore goes to wrong device

Symptom: Data was restored to the original device instead of the intended target.

Cause: The target device wasn’t explicitly specified in the restore wizard.

Fix: When restoring, explicitly select the target device in the destination step. If omitted, the restore defaults to the snapshot’s original device. Both devices must be in the same organization.

Restore includes more files than I selected

Symptom: A selective restore of one file also restores other, unrelated files that happen to share the start of the same name or path (for example, restoring report.txt also restores report.txt.bak and report.txt2).

Cause: Selective restore currently matches a selected path as a text prefix rather than an exact path, so any file whose path starts with a selected path is included.

Fix: This is a known issue with no workaround yet. For an in-place restore, avoid selecting individual files that have similarly-named siblings — restore to an alternate path instead and copy back only the file you intended.

Restore or verification will not start

Symptom: Starting a restore or verification returns an error immediately.

Cause: The target device is offline, disconnected, or the command pipeline could not queue the agent command.

Fix:

Confirm the destination device shows as Online in Breeze.
Verify the Breeze agent service is running and can reach the API.
If the error mentions queue or dispatch failure, check Redis and API logs for command queue errors.
Retry after the connectivity or queue issue is resolved.

Breeze does not create simulated verification records or silent pending restores in this case. The action fails explicitly so operators can correct the underlying issue first.

No verification history

Symptom: The Verification tab shows No verification history. Run a verification to check backup integrity.

Cause: No completed live verification has run yet for that device, or all recent attempts were skipped because the device was offline.

Fix:

Bring the device online.
Run an Integrity Check or Test Restore manually.
Review scheduled verification logs if the device is frequently offline during verification windows.

Dashboard shows 0 protected devices

Symptom: Backup dashboard reports no devices are protected, but policies exist.

Cause: The protection count is based on direct device assignments in policies. Devices targeted only through site or device group assignments are resolved at runtime and may not appear in this count.

Fix: If you need accurate coverage reporting, ensure policies include explicit device assignments. Alternatively, check individual device backup tabs to confirm they have a policy assigned.

VSS writers in Failed state

Symptom: The device backup tab shows one or more VSS writers as Failed.

Cause: A Windows service that provides a VSS writer is not running or is in an error state (common with SQL Server, Exchange, or Hyper-V writers).

Fix:

On the Windows device, run vssadmin list writers to see writer status.
Restart the service associated with the failed writer.
If the writer is not needed for your backup scope, it can be ignored — file backups will fall back to file-level copy if VSS is unavailable.

SLA breach alerts firing unexpectedly

Symptom: Receiving RPO or RTO breach notifications when backups appear to be running normally.

Cause: The SLA target may be tighter than the actual backup frequency, or test restore times are exceeding the RTO target.

Fix:

Review the SLA configuration — ensure RPO targets are compatible with your backup schedule (e.g., a 30-minute RPO requires backups at least every 30 minutes).
For RTO breaches, check whether the measured restore time in verification results exceeds the target. Consider faster storage (local vault) or smaller backup scope.

SQL Server backup chain broken

Symptom: Differential or log backups fail with a chain continuity error.

Cause: A full backup is needed to start a new chain. This happens after a database restore, a backup to a different tool, or a missed full backup.

Fix: Run a manual Full backup for the affected database from the SQL Server tab. Subsequent differential and log backups will chain from it.

Hyper-V export fails

Symptom: VM backup job fails during export.

Cause: Common causes include insufficient disk space at the export path, the VM being in an unsupported state, or Hyper-V integration services not running in the guest.

Fix:

Check available disk space at the export destination.
Verify the VM state — exports work best when the VM is Running or Off.
For application-consistent exports, ensure Hyper-V integration services are installed and running in the guest OS.
Try a crash-consistent export if application-consistent fails — but not for a VM that is Off. Known issue in v0.120.0: a crash-consistent backup of a powered-off VM fails with failed to save VM state … Save-VM; use Application-consistent for powered-off VMs.

Whole-machine restore looks stuck for a long time

Symptom: A bare-metal rebuild, bare-metal recovery, VM restore, or SQL Server restore is still “in progress” after an hour or more.

Cause: These restores download and verify one object at a time, so real hardware and large disks commonly take one to several hours — that alone isn’t a failure. Breeze allows up to 24 hours before treating a whole-machine restore as stalled.

Fix: Let it continue; check the recovery’s timeline (or the device’s command history) for phase progress. If it’s genuinely stuck, it’s automatically marked failed once it exceeds 24 hours — investigate storage throughput or network connectivity to the target at that point.

DR plan execution or save fails with a generic error

Symptom: Running a DR plan fails immediately, or saving a plan reports failure without saying what’s wrong.

Cause: A recovery group is missing a prerequisite — commonly a bare-metal rebuild group with no bare-metal-restorable snapshot, no valid rebuild host, or a device reference that no longer resolves to anything, or a rebuild step’s output directory isn’t a valid absolute path.

Fix: The execution error now names the specific missing prerequisite (for example “no restorable snapshot”) instead of a generic error — resolve that and retry. Saving a plan now validates group configuration before writing anything, so an invalid step is refused with nothing changed; if a save still fails partway through a multi-group plan, Breeze reports it as a partial save and refreshes the plan list automatically rather than leaving it out of sync with the server.

Bare-metal recovery fails with no reason shown

Symptom: A bare-metal recovery (boot media or rebuild engine) reports Failed, but the recovery details in the Recovery Bootstrap tab show nothing beyond “failed.”

Cause: Older agents didn’t always report why a system-state artifact failed to apply during recovery.

Fix: Current agents record the specific failure reason (for example, which artifact failed verification) and show it directly on the recovery. If you still see a blank reason, update the recovering agent and retry.

Post-restore validation flags healthy services as failed

Symptom: After a bare-metal recovery, the post-restore validation probe lists a template-style unit (e.g. getty@.service) or a one-shot systemd unit as unhealthy, even though the recovered system is fine.

Cause: Earlier validation probes checked template and one-shot units the same way as regular long-running services, even though those are never continuously “running” on a healthy system.

Fix: This is fixed in current agents — the probe now skips template units and evaluates one-shot units by their actual state, so only real regressions are flagged. Update the agent if you still see this.

Recovery token not working

Symptom: Bare metal recovery agent rejects the recovery token.

Cause: The token may have expired, been used already, or was copied incorrectly.

Fix: Generate a new recovery token. A token is consumed once a recovery completes with it and stops working when it expires; a recovery that failed before completing does not consume it, so Token is used means a recovery already finished with that token. Ensure you copy the full token string without trailing whitespace.

Generating bootable recovery media fails

Symptom: Building bootable recovery media (ISO) or a recovery bundle for a token, from the Recovery Bootstrap tab, shows a Failed status.

Cause: On some deployments, building recovery media runs out of temporary disk space on the server.

Fix: Retry the request — transient load can also cause a failure. If it fails consistently, contact your Breeze administrator; the server’s temporary storage may need to be increased. This affects both the ISO and the downloadable recovery bundle.