From 122b3bb382f57228fe7576c9b0b7c3ca19d863a3 Mon Sep 17 00:00:00 2001
From: Jah-yee <jydu_seven@outlook.com>
Date: Fri, 24 Apr 2026 00:14:06 +0800
Subject: [PATCH 1/2] fix: Improve DBAccessError messages to guide users on
 permission/directory issues
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Expanded DBAccessError docstring to mention directory missing and
  file permissions as potential causes
- Split the combined if-check into separate if/elif branches with
  distinct, actionable messages for each SQLite error:
  - 'unable to open database file' → suggests checking directory exists and is writable
  - 'attempt to write a readonly database' → suggests checking file/directory permissions

Addresses: beetbox/beets#1676
---
 beets/dbcore/db.py | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

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

From 8ce49d6152e7f6db0a8be7de7ba121e89943e1cf Mon Sep 17 00:00:00 2001
From: Jah-yee <166608075+Jah-yee@users.noreply.github.com>
Date: Tue, 28 Apr 2026 12:12:57 +0800
Subject: [PATCH 2/2] changelog: add entry for DBAccessError message
 improvement

Signed-off-by: Jah-yee <166608075+Jah-yee@users.noreply.github.com>
---
 docs/changelog.rst | 3 +++
 1 file changed, 3 insertions(+)

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