Troubleshooting

Most problems come down to one of three things: a report that did not arrive, a report that arrived but could not be matched or read, or an alert held back by a rule you set. Each section below says why it happens and what to do.

A report landed in the Inbox

A report email that reached BackupSentinel but could not be applied to a backup waits in the Inbox, under Needs review. Needs attention also lists it as "N emails not matched to a backup" for that client. It is marked Not assigned when:

• It reached a client address and no job name could be read from it. Only the Veeam, Synology and Duplicati rules read a job name, so for other products one client address can only feed one backup.
• A job name was read, but no backup of that client has that name yet.

What to do, from the email in the Inbox:

• Assign to a backup if the backup already exists. The email is applied to it.
• Start monitoring if it is a backup you are not watching yet. This creates the backup, within your plan's job limit, and assigns the email to it.
• Ignore it if you do not need it. You can Restore it later.

To stop it happening again for a product that does not read job names, give each backup its own address: the per-job address shown in the backup's details. See Client addresses.

No result read

No result read means a parsing rule matched the email but found none of its success, warning or failure words, so BackupSentinel cannot tell how the backup went. Nothing is assumed, and the email does not change the backup's status. Needs attention lists these as "N emails with no readable result".

Common causes are a backup product that changed its email wording, a language other than the one the rule expects, or a product without a built-in rule.

What to do:

1. Open the email in the Inbox. It shows which rule read it.
2. Use Test this rule on this email to see what the rule finds.
3. Create a rule for these emails, or customise the built-in rule, and add the words the email uses for success, warnings and failure. Test it against the email before you save.

New reports are then read with your rule. See Parsing rules.

A backup shows Missing but ran

Missing means no report was applied to the backup within its interval plus grace. The backup may well have run. Check these in order:

• The report never left. Check the backup software's email settings and that it sends a report after every run, including successful ones, not only on failure.
• It went to the wrong address. Compare the address in the backup software with the one in BackupSentinel, character by character.
• It arrived but was not applied. Look in the Inbox for an email marked Not assigned or No result read, and fix it as above.
• The interval is too short. The next report is due one interval after the last one was received, not after the backup ran. A daily job that runs only on weekdays turns Missing at the weekend. Choose an interval that covers the longest normal gap.
• The report arrived late. Delayed email counts from when it was received, so a report that was held up for hours can miss the window.
• It was a Synology integrity check. An integrity-check report is not a backup run and does not reset the clock.

When the next report arrives, it sets the status again, and a successful one resolves the alert. See Job statuses.

A backup is stuck on Waiting

Waiting means no report has been applied to the backup since you created it. It cannot stay Waiting for ever: if no report arrives within one interval plus grace of creating it, it turns Missing.

While it is Waiting, check:

• That the backup software has run since you set it up, and sends its report to the right address.
• The Inbox, for a report from this backup marked Not assigned (assign it) or No result read (fix the rule).
• For Veeam, Synology and Duplicati at a client address: that the backup's name in BackupSentinel matches the job name in the report.
• For reports sent through the API: that the request returned 200. See Report API.

An alert did not arrive

Start with the alert itself. Each alert in Needs attention has a delivery line under it: "Sent to N channels", with "N failed" and "N skipped" when that applies, or "Not sent".

• Not sent: no alert channel covered the alert. Needs attention shows "No alert channel set up" when you have none. Also check whether the channel is limited to some clients, or set to escalation-only.
• Failed: the channel rejected the message. Needs attention shows "Alert channel failing" for any failed delivery in the last 24 hours. Check the webhook, routing key or email address in Settings → Alert channels, and use Send test for Email, Slack or Teams. Failed sends are retried every 10 minutes, up to five attempts, while the alert is open.
• Skipped during quiet hours: warnings that fire during quiet hours are not sent, and are not sent later either. Failures and missing reports always go out.

Other reasons an alert does not reach you:

• PagerDuty receives critical alerts only. Warnings never go to PagerDuty.
• The email cap. A backup that flaps sends at most 100 alert emails in 24 hours. Needs attention shows "Email alerts paused for N flapping backups".
• The client is paused or archived. No alert is created for its backups.
• An alert is already open. Each backup has one open alert. Another failure while it is open does not open or send a second alert. A warning that becomes a failure raises the same alert to critical.
• Email filters. Check the spam folder and any mail rules on the recipient's side.

See Alerts and channels.

A Backup shrank item

"Backup shrank N%" means the newest successful or warning run reported a size of half or less of its usual size: the median of up to seven earlier runs. It needs at least three earlier runs with a size, and a usual size of at least 1 MiB, and only looks at the last 14 days.

A sudden drop can mean data or machines were left out of the backup, a source disk went offline, or files were deleted on the source. It can also be expected, after you removed a machine from the job or cleaned up data.

• Check what the backup covered in the backup software's report.
• If the drop is expected, choose Expected on the item to hide that drop.

Size drops show in Needs attention only. They are never sent to alert channels.

A 429 or 401 from the API

• 401 means the key was not accepted. The message says why: "Missing or malformed Authorization header" (the header must read Bearer followed by the full key), "Invalid API key" (mistyped, or revoked in Settings → API keys) or "API key has expired". Create a new key if you no longer have the full one: a key is shown only once.
• 429 with "max 60 requests/minute" means the key sent more than 60 requests in a minute. Slow down or spread the work across keys.
• 429 with "Daily ingest cap" means the job has had 100 reports in the last 24 hours. The report was not recorded. Check the script is not reporting in a loop.

The Report API page lists every error.

Reports stopped after the trial or a failed payment

When a trial ends without a plan, or a payment fails for the third time, the workspace is suspended. While it is suspended, report emails are skipped and not stored, API reports are refused with 403 Workspace suspended, no backup turns Missing and no alert is sent.

What to do:

• Choose a plan in Settings → Billing, or update the card with Manage billing in Stripe after a failed payment. A successful payment lifts the suspension automatically.
• Monitoring resumes with the next report each backup sends. Reports sent while the workspace was suspended were not kept, so they cannot be recovered.

Your clients, jobs and settings are kept throughout, and the full data export works while suspended. See Billing and plans.

Still stuck

Contact us with the client and backup name and what you expected to see. If it helps to look inside your workspace, BackupSentinel support can open it to help with the problem you report, and everything done that way is labelled in your activity log.