Backup Job Errors

When a backup does not produce a restore point, the Manager records why as an error code and a sentence. The code is shown in the Cause column on the Backup Jobs screen, the sentence under What went wrong in the job's detail sheet, and both in cdr jobs list --failed --detail. Reports count failures by code. For the screen, see Backup Jobs.

Backups that do not start

Before it starts a backup, scheduled or on demand, the Manager checks five things. A backup that fails a check does not start:

Code	Meaning and what to do
`backup-already-in-flight`	A backup of the machine is already queued or running. Wait for it to finish. No failed job is recorded.
`dc-agent-unavailable`	No DC agent is connected for the machine, so no backup can be taken. A failed job is recorded. Check the agent; see Agent Enrollment and Connectivity. A refusal made before the machine's current agent enrolled, or while it has no agent, still appears on the Backup Jobs screen but does not make the domain controller's last backup count as failed or raise the last-backup-failed alert.
`license-inactive`	Shown as No active license. No license key is installed, the installed key does not license Cygna Forest Recovery for Active Directory, or the license has ended and its grace period is over. The Manager checks this first. No failed job is recorded: the Backups and recovery operations stopped: no active license alert and the banner on every screen say why backups have stopped. A manual backup is refused with the license's sentence as the reason. Scheduled backups stay due and start by themselves once a current key is applied. See Licensing.
`recovery-in-progress`	Shown as A recovery is working on this DC. A recovery plan is running over the machine, a restore run on it is in progress, or a plan recovered it in the last 2 hours and its DC agent has not connected yet. No failed job is recorded. A manual backup is refused. A scheduled backup waits and starts by itself when the recovery is done. Test restores do not hold backups.
`storage-agent-unavailable`	No storage agent is connected. A failed job is recorded. Check that the storage agent service is running and connected.

Job error codes

Code	Shown as	Cause and what to do
`staging-insufficient-capacity`	Insufficient staging capacity	The storage agent refused to accept the backup because the vault volume does not have room for its estimated size plus the free space reserve, and retention found nothing it was allowed to delete. Add capacity or reduce retention; see Retention. The Repository screen shows capacity and the space reserved for running backups.
`staging-credential-mint-failed`	Staging account could not be created	The storage agent could not create the local account the domain controller writes the backup with. Read the storage agent's log for the reason. The storage agent must run as LocalSystem on a machine where it is a local administrator.
`staging-mint-failed`	Staging credential could not be issued	The storage agent could not prepare staging for the backup for another reason. Read the storage agent's log at the time of the job.
`backup-timeout`	Backup not reported in time	The domain controller did not report the backup within the Backup job timeout. (If the DC agent restarted during the backup, the job is closed as `agent-interrupted` instead, as soon as the agent reconnects.) The backup was not cancelled: wbadmin is most likely still running, and if it finishes, the agent reports it and the backup is still committed. Wait, then check the job again. If large DCs regularly take longer, raise Backup job timeout, keeping the storage agents' Reservation timeout at least 30 minutes longer.
`agent-interrupted`	DC agent restarted during the backup	The DC agent stopped while the backup was running—during an agent upgrade, a crash, or a restart of the machine—and came back without it, so the outcome was not captured. The job's status is Interrupted. wbadmin is left running when the agent stops and may have finished: check the Microsoft-Windows-Backup event log on the domain controller. Nothing from this run was committed to the vault, even if wbadmin finished, so take another backup. To avoid this, upgrade DC agents outside backup windows.
`agent-reported-failure`	Agent reported a failure	The DC agent or wbadmin reported that the backup failed. The detail sheet gives the agent's error and the transcript. See Common causes.
`vault-commit-failed`	Vault commit failed	The backup finished on the domain controller, but the storage agent could not hash it and move it into the vault. Read the error in the detail sheet and the storage agent's log.
`vault-commit-timeout`	Vault commit not confirmed in time	The storage agent did not report the commit within the Vault commit timeout. The commit was not cancelled and is most likely still running, so look for the backup in the vault before looking in staging. If it happens often, raise Vault commit timeout.
`storage-agent-unavailable`	Storage agent unreachable	The storage agent was not connected when the job needed it.
`dc-agent-unavailable`	DC agent unreachable	The DC agent was not connected when the job needed it.
`backup-already-in-flight`	A backup is already running	Another backup of the machine was already queued or running.
`operator-cancelled`	Cancelled by an operator	An operator cancelled the backup. The job's status is Cancelled.
`orchestrator-fault`	Internal manager error	An unexpected error in the Manager. Read the Manager's log at the time of the job, and contact support if it recurs.

Two codes can appear on a job that completed:

Code	Shown as	Meaning and what to do
`version-id-uncaptured`	Backup version identifier not captured	The backup completed and is in the vault, but the wbadmin version identifier was not recorded, so it cannot be chosen as a restore point. Take another backup of the machine, and read the DC agent's transcript for why the identifier was missing.
`vault-commit-reconciled`	Vault commit confirmed late	The commit was confirmed after the Manager had stopped waiting for it, and the job was corrected when the result arrived or when the Manager next checked the storage machine. The restore point is good. The error says why the Manager stopped waiting. Raise Vault commit timeout only when it says the commit took longer than that setting; a commit reported across a Manager restart needs nothing.

Job statuses that need attention

Completed (unreconciled)—The Manager could not confirm the job against the vault. Treat the restore point as uncertain, and take another backup.
Completed, not committed—The domain controller produced the backup, but the Manager did not see its content reach the vault. It is not yet a restore point. The Manager checks the storage machine for these every hour and whenever the storage agent connects, well within the time after which Delete abandoned staging folders removes an idle folder. Content still in staging is committed, and content already in the vault is recorded, so the job becomes Completed. To check now, select Check now under Backups not in the vault on the Repository screen, or run cdr repository uncommitted --check. A job whose content is found in neither place stays as a record and is not a restore point. Take another backup.
Interrupted—The job stopped before it finished and its outcome was not captured: the DC agent restarted during the backup (for example during an agent upgrade, with the code agent-interrupted), or the Manager restarted and the agent did not report the job's outcome afterward. A Manager restart during the vault commit does not interrupt the job: the storage agent finishes the commit, and the job completes. Nothing from an interrupted run was committed to the vault. Take another backup. An interrupted backup counts as a failed attempt in alerts and reports.

Common causes

Symptom	Cause and fix
Every backup of a DC fails, and the transcript says the system cannot find the file specified	The Windows Server Backup feature is not installed on the domain controller. The DC agent installs it when Install the Windows Server Backup feature is on, which is the default. If the setting has been turned off for that DC, install the feature by hand or turn the setting back on. The DC agent's log says at startup whether the feature is present. If the setting is on and the agent's install attempt failed, a restart still pending on the domain controller (after a promotion, for example) is the usual cause: restart the domain controller, and the agent tries again at startup. The job's error message says which of these applies.
Backups from every DC fail to connect to staging	No share publishes the staging folder on the storage machine. Create an SMB share over `<storage root>\staging`; see Setting Up the Storage Machine.
Backups fail with a logon failure to staging	The staging share's permissions do not admit the staging writers group, so every per-job account is refused. Leave Manage the staging share's permissions on, or grant the group Change permission on the share. A deny entry is reported as an error and must be removed by hand.
Backups fail from some DCs but not others	The storage machine has several addresses and advertises one the failing DCs cannot reach, or advertises its name. Set Advertised host to the address the DCs reach; see Agent Enrollment and Connectivity.
Backups are refused for capacity	The vault is full or tight. See the Vault refusing backups and Vaults with no room for another version alerts in Alerts Reference.
Timeouts when many DCs back up at once	Backups and commits share the storage machine's disks. Raise Backup job timeout and Vault commit timeout, or lower Maximum concurrent backups.

For running and cancelling backups, see Monitoring and Cancelling Backup Jobs.