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

Open Beginner friendly
#436 0 comments 0 reactions 0 assignees View on GitHub

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:

  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: 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from navidrome/website

All issues in navidrome/website

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.