Skip to content

fix: Improve DBAccessError messages for permission/directory issues #6579

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
snejus merged 2 commits into from
Apr 28, 2026
+17 −7
Merged

fix: Improve DBAccessError messages for permission/directory issues #6579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
122b3bb
fix: Improve DBAccessError messages to guide users on permission/dire…
Jah-yee Apr 23, 2026
8ce49d6
changelog: add entry for DBAccessError message improvement
Jah-yee Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 14 additions & 7 deletions beets/dbcore/db.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,9 @@ class DBAccessError(Exception):
"""The SQLite database became inaccessible.

This can happen when trying to read or write the database when, for
example, the database file is deleted or otherwise disappears. There
is probably no way to recover from this error.
example, the database file is deleted, the parent directory is missing,
or the file permissions prevent the operation. There is probably no way
to recover from this error.
"""


Expand Down Expand Up @@ -1024,11 +1025,17 @@ def _handle_mutate(self) -> Iterator[None]:
# In two specific cases, SQLite reports an error while accessing
# the underlying database file. We surface these exceptions as
# DBAccessError so the application can abort.
if e.args[0] in (
"attempt to write a readonly database",
"unable to open database file",
):
raise DBAccessError(e.args[0])
if e.args[0] == "unable to open database file":
raise DBAccessError(
"unable to open database file. "
"Check that the parent directory exists and is writable."
)
elif e.args[0] == "attempt to write a readonly database":
raise DBAccessError(
"attempt to write a readonly database. "
"Check file permissions: the database file or its directory "
"may not be writable."
)
raise
else:
self._mutated = True
Expand Down
3 changes: 3 additions & 0 deletions docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,9 @@ Bug fixes
``Feat.`` join text) and ``extraartists`` as ``Featuring``. :bug:`6166`
- :ref:`import-cmd` Metadata source plugin ID lookups now correctly call each
plugin's own lookup method when running in parallel. :bug:`6583`
- Improve ``DBAccessError`` messages to help users diagnose database permission
issues more easily. The error message now mentions directory missing and file
permissions as potential causes. :bug:`1676`

..
For plugin developers
Expand Down
Loading