Repository Maintenance
Interpret repository health states and use Doctor, Unlock, and stats refresh correctly
The repository details page exposes a small set of maintenance tools, but they do different jobs. This guide explains what each status means and what the built-in actions actually do.
Repository status values
| Status | What it means in Zerobyte | What to do next |
|---|---|---|
healthy | The last stored health verdict finished without errors | Keep monitoring and refresh stats when you want updated size metrics |
error | The last health or doctor run recorded an error | Review Last Error and the Doctor Report, fix the underlying issue, then rerun maintenance if needed |
unknown | Zerobyte does not currently have a fresh health verdict, or repository settings were changed and the old verdict was cleared | Expect this after some config changes; verify access and consider running Doctor |
doctor | A Doctor run is in progress | Wait for it to finish or cancel it during a maintenance window |
cancelled | A Doctor run was aborted before completion | Review any partial Doctor output and rerun Doctor if you still need validation |
Repository status is stored metadata inside Zerobyte. It is not a continuous live probe.
What each action really does
| Action | What it does | What it does not do |
|---|---|---|
Run doctor | Runs unlock, then check, then repair-index if restic says it is needed. Saves step output into the Doctor Report. | It does not run a full check --read-data scrub, it does not prune unused data, and it does not refresh the stats card. |
Unlock | Runs restic unlock --remove-all to clear stale repository locks. | It does not validate repository integrity and it does not change the stored health status by itself. |
| Stats refresh button | Runs restic stats --mode raw-data and updates stored size and snapshot metrics. | It does not change repository health status, Last Checked, or the Doctor Report. |
Run doctor in detail
Doctor is the deepest repository-maintenance action currently exposed in the normal UI.
During a Doctor run, Zerobyte:
- Sets the repository status to
doctor - Acquires an exclusive repository lock inside the app
- Runs an unlock step
- Runs
restic check - Runs
restic repair-indexonly if the check output suggests that repair - Saves the step-by-step result and updates the final status to
healthy,error, orcancelled
Because Doctor holds an exclusive repository lock, it can block other repository operations such as backups, restores, and snapshot mutations while it runs.
Doctor is helpful, but it is lighter than a full offline integrity scrub. Today it does not read every stored data pack and it does not prune repository data. Treat healthy as a useful application-level signal, not as proof that every blob was recently re-read.
When to use Run doctor
- The repository status is
error - Last Error suggests metadata or index problems
- Operations keep failing after a crash or interrupted run
- You changed repository settings and want a fresh maintenance pass
- You want a stored Doctor Report before or after backend maintenance work
When to use Unlock
Use Unlock when the problem is specifically stale repository locks, for example after:
- A crashed backup or restore
- A forced container restart
- A cancelled or interrupted maintenance run
- A Restic message that says the repository is locked
If the problem is not a lock issue, Unlock will not fix it.
Only run Unlock when you are certain no real backup, restore, or maintenance operation is still using that repository.
What stats refresh actually recalculates
The refresh button in Compression Statistics recalculates repository metrics using restic stats --mode raw-data, including:
- Stored size
- Uncompressed size
- Compression ratio
- Compression progress
- Compression space saving
- Snapshot count
This is useful when:
- The stats card is still empty after connecting an existing repository
- You deleted snapshots and want updated numbers
- Retention cleanup changed repository usage
- You want fresh size numbers without running Doctor
Reading the Doctor Report
The Doctor Report stores each maintenance step with its output and any error text. In current builds, the steps you will typically see are:
unlockcheckrepair_indexwhen suggested by restic
If a Doctor run is cancelled, the report can still contain partial step output from the work that completed before cancellation.
Practical workflows
Repository is locked after a crash
- Use Unlock.
- Retry the blocked backup or restore.
- If problems continue, run Doctor.
Status is unknown
- Check whether you recently edited repository settings.
- Use the stats refresh button if you only need updated size numbers.
- Run Doctor if you want a fresh maintenance verdict.
Status is error
- Read Last Error.
- Expand the Doctor Report and identify the failing step.
- Fix the real problem first, such as credentials, backend reachability, or repository corruption.
- Run Doctor again after the fix.