[Docs]: backup restore needs an existing database, and --backup-file is a name inside Backup.Path
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 65/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- hugo
- Domain
- documentation
Research direction
Open docs/usage/admin/backup/ and compare the restore instructions with the reported Navidrome 0.63.2 Docker sequence and output. Update the restore section to document the existing-database prerequisite, Backup.Path or ND_BACKUP_PATH, filename semantics for --backup-file, and --force; confirm the wording against the server-side report before considering it done.
Written by the indexing model from the issue text.
Description
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:
-
It refuses to run without an existing database.
level=fatal msg="No existing database" path=/data/navidrome.dbThat 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. -
--backup-fileis not documented, and it is not a path. The value is resolved
insideBackup.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_PATHhas to be configured for the restore as well. -
--forceis 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-filetakes a file name insideBackup.Path, not a path, soBackup.Path
(orND_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: https://github.com/navidrome/navidrome/issues/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.
- Dominant language
- JavaScript
- Stars
- 42
- Forks
- 229
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 23
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from navidrome/website
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
documentation enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
[Docs]: Opendocumentation
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
documentation
Difficulty 3/5 1-2 days Newbie friendliness 55/100
-
documentation
Difficulty 4/5 3-5 days Newbie friendliness 35/100
All issues in navidrome/website
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
HarperFast/skills#96 ·
-
[Block] Latest Posts [Type] Bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Automattic/studio#4908 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
sugarlabs/musicblocks#8847 ·