[Docs]: backup restore needs an existing database, and --backup-file is a name inside Backup.Path

[spelingbee]

I confirm that:

• This issue is about the documentation website, NOT about the Navidrome server

Page URL or path

https://www.navidrome.org/docs/usage/admin/backup/

What's wrong

The page is unusually good - the scope note ("ONLY backs up the database ... does NOT back up the music or the config") is the sentence most projects are missing. The restore section is three sentences, and following it exactly on 0.63.2 in Docker does not work:

1. It refuses to run without an existing database.

   level=fatal msg="No existing database" path=/data/navidrome.db
   

   That is the state a new machine is in, which is the machine people restore onto. The
   working sequence is: start Navidrome once so it creates a database, stop it, then
   restore - and the page's two warnings are both about not having it running, which
   makes the missing step easy to reason past.

2. --backup-file is not documented, and it is not a path. The value is resolved
   inside Backup.Path. Given an absolute path, the command fails with an empty path in
   its own error message:

   level=fatal msg="Error restoring database" backup path= \
     error="getting backup connection: unable to open database file: no such file or directory"
   

   so Backup.Path / ND_BACKUP_PATH has to be configured for the restore as well.

3. --force is not documented either, and without it the command asks a question
   that no script can answer.

Suggested fix

Replacement for the restore section:

Restoring requires a database to already exist. On a new machine, start Navidrome
once so that it creates one, stop it, and then run the restore.

navidrome backup restore --backup-file navidrome_backup_2026.01.02_03.04.05.db --force

--backup-file takes a file name inside Backup.Path, not a path, so Backup.Path
(or ND_BACKUP_PATH) must be set when restoring as well as when backing up.

I would be glad to send a PR for that if it would be welcome. It is worth holding until the server-side report is resolved, since the sequence above currently ends in Restore complete and an empty instance: navidrome/navidrome#6083.

---

Everything above, with the commands and the unedited output, is at https://github.com/spelingbee/drillback/tree/main/docs/drill/navidrome - one leg of a restore drill across fifteen self-hosted applications, each one following its own backup documentation as written.