Troubleshoot failing backups
When a backup fails, Dockstash tells you loudly and shows you exactly where: an alert email with the error, a status badge on the project card, and the full restic output in the live log panel. This guide walks the common failure shapes — from red runs to offline agents to the silence alarm — and their fixes.
How to do it
Start at the project card
The Projects screen shows a status badge, last backup time, and size per project. A failed run also arrives as an alert email carrying the error and a deep link — start from either. The project detail view surfaces the last failure detail directly.
Read the run’s restic output
Open the log panel for the failing run. The last lines almost always name the cause: authentication failed (SSH key or DB credentials), no space left on device (storage box full), connection refused (storage VPS unreachable), or a dump command error from inside the container.
Stale restic locks fix themselves
If a run crashed or the server rebooted mid-backup, the repository can be left locked. You do not need to intervene: the next run detects the orphaned lock and runs restic unlock automatically. A live-held lock from a genuinely running job is never broken.
Agent projects: check the agent first
If a fleet-agent project stops backing up, check the Fleet screen. An offline agent means heartbeats stopped: on the VPS confirm both agent containers are up, the Dockstash URL is reachable, and the token was not rotated without updating the container. Repeated 401s in the logs mean an old container somewhere still uses a revoked token.
docker compose -f docker-compose.agent.yml psUnderstand "no backup ran" alerts
A heartbeat alert means no successful backup landed inside the window — nothing errored, nothing ran. Usual suspects: the schedule was disabled, the plan tier does not allow schedules, the project was paused after a downgrade, or the assigned agent is offline. Fix the cause and the next green run clears the alarm.
Do it in one click with Dockstash
Dockstash runs the exact dump above, restics it off-site, and drill-tests the restore automatically — no script to maintain.
Last updated: July 2026
Related guides
Connect a fleet agent
Run a small outbound-only agent on any VPS and back up its containers from one dashboard — registration, install, project directories, and first assignment.
Set up alerts & notifications
Failure emails, a dead-man’s-switch heartbeat that catches silent stalls, webhook fan-out to Slack or PagerDuty, and an immutable audit trail.
MySQL
Back up MySQL in Docker
MongoDB
Back up MongoDB in Docker
Frequently asked questions
A backup failed once and succeeded on retry. Should I care?
Look at the failure reason. Jobs retry with capped exponential backoff, so transient network blips self-heal. Recurring retries on the same error — disk filling up, flaky SSH — deserve a real fix before they become a hard failure.
Why does my second schedule wait instead of running?
One job per repository at a time, always. Concurrent restic operations corrupt repositories, so colliding schedules on the same repo are serialized deliberately. Different repos run in parallel.
The Add-Project picker for my agent is empty. Why?
The picker reads the snapshot the agent pushed on its last heartbeat. Empty means the agent has not reported yet, a project root is not actually mounted into the agent container, or the Docker socket proxy is unreachable — the picker banner tells you which. Fix it, then hit Refresh now instead of waiting for the next discovery cycle.
How do I prove the repository itself is healthy?
Run a check job. restic check verifies repository structure; with a read-data subset percentage it also reads and verifies actual pack contents. Pass requires a zero exit code — there are no false greens.
Where do I see why a drill failed?
The drill result stores a detail message including the mismatch count, shown on the Restore drill tab and in the alert email. Byte mismatches point at files changing during backup; row mismatches point at dump consistency — both mean treat the backup as unproven until a re-run passes.