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.

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.

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. Tokens are single-use and time-limited. 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.