diff --git a/beets/dbcore/db.py b/beets/dbcore/db.py index 664dc93e90..140f1d4d0a 100755 --- a/beets/dbcore/db.py +++ b/beets/dbcore/db.py @@ -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. """ @@ -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 diff --git a/docs/changelog.rst b/docs/changelog.rst index 3eebfc0848..7a2528c17a 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -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