Improve error message when database directory is not writable

[VedantMadane]

Adds better error handling for SQLite OperationalError when the database file or directory is not writable. When the error message contains 'readonly' or 'unable to open', provides a helpful message suggesting the user check directory permissions. Also fixes a typo in the error message ('cannot not' to 'could not'). Closes #1676

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• The special-case readonly/unable to open branch currently assumes a directory permissions issue; consider broadening the message to mention both file and directory permissions (or phrasing it more generically) since these errors can also arise from file-level ACLs or missing paths.
• When constructing db_dir = os.path.dirname(dbpath), it may be safer to normalize the path (e.g., via os.path.abspath) and handle the case where dbpath has no directory component, so that the resulting message about the directory being writable is always meaningful.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The special-case `readonly`/`unable to open` branch currently assumes a directory permissions issue; consider broadening the message to mention both file and directory permissions (or phrasing it more generically) since these errors can also arise from file-level ACLs or missing paths.
- When constructing `db_dir = os.path.dirname(dbpath)`, it may be safer to normalize the path (e.g., via `os.path.abspath`) and handle the case where `dbpath` has no directory component, so that the resulting message about the directory being writable is always meaningful.

## Individual Comments

### Comment 1
<location> `beets/ui/__init__.py:1513-1518` </location>
<code_context>
+        # Check for permission-related errors and provide a helpful message
+        error_str = str(db_error).lower()
+        dbpath_display = util.displayable_path(dbpath)
+        if "readonly" in error_str or "unable to open" in error_str:
+            db_dir = os.path.dirname(dbpath)
+            raise UserError(
+                f"database file {dbpath_display} could not be opened due to a "
+                f"permissions error. Please check that the directory "
+                f"{util.displayable_path(db_dir)} is writable."
+            )
         raise UserError(
</code_context>

<issue_to_address>
**issue (bug_risk):** The permission-specific branch may misdiagnose non-permission errors as permission issues.

Relying on the generic substring `"unable to open"` and mapping it directly to a permissions error is brittle. This message can also arise from non-permission issues (missing directory, malformed path, unavailable filesystem). Please either narrow the pattern to permission-specific cases, include the original `db_error` in the message for context, or soften the wording so it doesn’t claim permissions are the only cause.
</issue_to_address>

### Comment 2
<location> `beets/ui/__init__.py:1512-1522` </location>
<code_context>
+        dbpath_display = util.displayable_path(dbpath)
+        if "readonly" in error_str or "unable to open" in error_str:
+            db_dir = os.path.dirname(dbpath)
+            raise UserError(
+                f"database file {dbpath_display} could not be opened due to a "
+                f"permissions error. Please check that the directory "
+                f"{util.displayable_path(db_dir)} is writable."
+            )
         raise UserError(
</code_context>

<issue_to_address>
**suggestion:** The permission-focused message drops the original SQLite error details, reducing debuggability.

In this branch, the original `db_error` isn’t surfaced, unlike in the generic error path. Please include it here as well (e.g., by appending `f" (original error: {db_error})"`) so callers retain the underlying SQLite details for troubleshooting.

```suggestion
        dbpath_display = util.displayable_path(dbpath)
        if "readonly" in error_str or "unable to open" in error_str:
            db_dir = os.path.dirname(dbpath)
            raise UserError(
                f"database file {dbpath_display} could not be opened due to a "
                f"permissions error. Please check that the directory "
                f"{util.displayable_path(db_dir)} is writable "
                f"(original error: {db_error})."
            )
        raise UserError(
            f"database file {dbpath_display} could not be opened: {db_error}"
        )
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

❌ Patch coverage is 77.77778% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.18%. Comparing base (137c049) to head (5f4c0cd).
⚠️ Report is 2 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
beets/ui/__init__.py	75.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #6294   +/-   ##
=======================================
  Coverage   70.18%   70.18%           
=======================================
  Files         147      147           
  Lines       18680    18688    +8     
  Branches     3042     3044    +2     
=======================================
+ Hits        13111    13117    +6     
- Misses       4927     4928    +1     
- Partials      642      643    +1     

Files with missing lines	Coverage Δ
beets/dbcore/db.py	94.15% <100.00%> (ø)
beets/ui/__init__.py	82.10% <75.00%> (-0.13%)	⬇️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[VedantMadane]

readonly errors only occur on write operations, not during database open. I've pushed a fix that removes the
readonly check and keeps only the unable to open check, which does occur here when the directory isn't writable and the database doesn't exist yet.

Also refined the error message to be more specific about the directory-not-writable-on-create scenario.

[snejus]

Maybe it'd be worth addressing this error message as part of this PR as well?

Really modify and move? (Yes/no/select) 

Traceback (most recent call last):
  File "/home/sarunas/.local/bin/beet", line 8, in <module>
    main()
  File "/home/sarunas/repo/beets/beets/ui/__init__.py", line 1661, in main
    _raw_main(args)
  File "/home/sarunas/repo/beets/beets/ui/__init__.py", line 1640, in _raw_main
    subcommand.func(lib, suboptions, subargs)
  File "/home/sarunas/repo/beets/beets/ui/commands/modify.py", line 105, in modify_func
    modify_items(
  File "/home/sarunas/repo/beets/beets/ui/commands/modify.py", line 63, in modify_items
    obj.try_sync(write, move, inherit)
  File "/home/sarunas/repo/beets/beets/library/models.py", line 1027, in try_sync
    self.move(with_album=with_album)
  File "/home/sarunas/repo/beets/beets/library/models.py", line 1166, in move
    self.store()
  File "/home/sarunas/repo/beets/beets/library/models.py", line 72, in store
    super().store(fields)
  File "/home/sarunas/repo/beets/beets/dbcore/db.py", line 656, in store
    tx.mutate(
  File "/home/sarunas/repo/beets/beets/dbcore/db.py", line 1016, in mutate
    cursor = self.db._connection().execute(statement, subvals)
sqlite3.OperationalError: database is locked

This happens whenever you try to write to the database while it is already being written.

You can re-produce it by opening two terminal windows:

1. Run beet modify path::aa aaa=bb in the first one
2. Run beet modify path::aa aaa=b in the second one
3. Accept (press Enter) in the first one, and in the second one immediately right after
4. See the second one fail with the error above.

[snejus]

@VedantMadane what do you think about this? Also note that CI is complaining about some lint issues.

Maybe it'd be worth addressing this error message as part of this PR as well?

Really modify and move? (Yes/no/select) 

Traceback (most recent call last):
  File "/home/sarunas/.local/bin/beet", line 8, in <module>
    main()
  File "/home/sarunas/repo/beets/beets/ui/__init__.py", line 1661, in main
    _raw_main(args)
  File "/home/sarunas/repo/beets/beets/ui/__init__.py", line 1640, in _raw_main
    subcommand.func(lib, suboptions, subargs)
  File "/home/sarunas/repo/beets/beets/ui/commands/modify.py", line 105, in modify_func
    modify_items(
  File "/home/sarunas/repo/beets/beets/ui/commands/modify.py", line 63, in modify_items
    obj.try_sync(write, move, inherit)
  File "/home/sarunas/repo/beets/beets/library/models.py", line 1027, in try_sync
    self.move(with_album=with_album)
  File "/home/sarunas/repo/beets/beets/library/models.py", line 1166, in move
    self.store()
  File "/home/sarunas/repo/beets/beets/library/models.py", line 72, in store
    super().store(fields)
  File "/home/sarunas/repo/beets/beets/dbcore/db.py", line 656, in store
    tx.mutate(
  File "/home/sarunas/repo/beets/beets/dbcore/db.py", line 1016, in mutate
    cursor = self.db._connection().execute(statement, subvals)
sqlite3.OperationalError: database is locked

This happens whenever you try to write to the database while it is already being written.

You can re-produce it by opening two terminal windows:

1. Run `beet modify path::aa aaa=bb` in the first one

2. Run `beet modify path::aa aaa=b` in the second one

3. Accept (press Enter) in the first one, and in the second one immediately right after

4. See the second one fail with the error above.

[snejus]

@VedantMadane I'm waiting for your response to my comments above.

[snejus]

Please mark it ready once you responded to my comments above @VedantMadane.

[VedantMadane]

@snejus Sorry for the delayed response! Here's what I've done:

1. Squashed the branch into a single clean commit rebased on current master. This cleans up the messy merge history.

2. Moved the changelog entry to the Unreleased section (it was stuck in 2.9.0 from before the release, which caused the Check docs CI failure).

3. Regarding the "database is locked" error: The busy timeout bump from 5s to 30s in this PR should significantly reduce the frequency of that error during concurrent access — SQLite will now retry for 30 seconds before giving up. For a dedicated user-facing error message for database is locked specifically (e.g., "another beets instance may be writing to the database"), I think that's better as a follow-up since it's a different code path (write-time vs. open-time). Happy to open that as a separate PR if you'd like.

Should be green now — please take another look when you get a chance.

[Copilot]

Pull request overview

PR try make beets give nicer UserError when SQLite fail open DB because permissions (like directory not writable). It also add tests for new message.

Changes:

• Add special-case handling in ui._open_library for SQLite “unable to open” errors to suggest checking file/dir write permissions.
• Add UI init tests that assert the improved error message and keep fallback message for other OperationalError cases.
• Change DB core default timeout and update changelog entry (plus some packaging metadata edits).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
beets/ui/__init__.py	Add permission-hint UserError when SQLite open fail.
test/ui/test_ui_init.py	Add tests for new database-open error message behavior.
beets/dbcore/db.py	Adjust DB init defaults (timeout) and tweak migration base.
docs/changelog.rst	Add unreleased note about improved DB open error message + timeout + typo fix.
pyproject.toml	Modify project version / classifiers / dependency constraints, plus ruff ignore for new test.

Comments suppressed due to low confidence (2)

beets/dbcore/db.py:1122

• grug see Database timeout default changed to 30s, but Library always passes timeout from beets.config['timeout'] (default in config_default.yaml still 5.0). so this change likely not actually increase default busy timeout for normal beets usage. either bump config default / docs, or wire new default into config path.

    def __init__(self, path, timeout: float = 30.0):
        if sqlite3.threadsafety == 0:
            raise RuntimeError(
                "sqlite3 must be compiled with multi-threading support"
            )

docs/changelog.rst:20

• grug see docs/changelog drop whole 2.9.0 section + many entries from Unreleased. looks like accidental conflict revert. changelog should not lose past release notes; please restore removed sections and only add new bugfix entry for #1676.

Unreleased
----------

New features
~~~~~~~~~~~~

- :ref:`import-cmd` Use ffprobe to recognize format of any import music file
  that has no extension. If the file cannot be recognized as a music file, leave
  it alone. :bug:`4881`
- Query: Add ``has_cover_art`` computed field to query items by embedded cover
  art presence. Users can now search for tracks with or without embedded artwork
  using ``beet list has_cover_art:true`` or ``beet list has_cover_art:false``.

[snejus]

@snejus Sorry for the delayed response! Here's what I've done:

1. **Squashed the branch** into a single clean commit rebased on current master. This cleans up the messy merge history.

2. **Moved the changelog entry** to the Unreleased section (it was stuck in 2.9.0 from before the release, which caused the Check docs CI failure).

3. **Regarding the "database is locked" error**: The busy timeout bump from 5s to 30s in this PR should significantly reduce the frequency of that error during concurrent access — SQLite will now retry for 30 seconds before giving up. For a dedicated user-facing error message for `database is locked` specifically (e.g., "another beets instance may be writing to the database"), I think that's better as a follow-up since it's a different code path (write-time vs. open-time). Happy to open that as a separate PR if you'd like.

Should be green now — please take another look when you get a chance.

Ah I see, this makes sense! Would you mind rebasing your PR and fixing the issues in CI? Please address the review comments from Copilot as well!

[VedantMadane]

@snejus Thanks for the patience and the review notes.

I have rebased onto latest master and am cleaning up CI (format/lint/mypy/tests) after the rebase. I will reply point-by-point on your earlier comments in a follow-up once the suite is green, then mark ready as you asked.

If anything in the rebased diff looks off vs what you reviewed before, I am happy to re-walk it.