Bug: Folder names containing parentheses cause FileNotFoundError and UI crash during import

[JoaoSobral]

Bug: Folder names containing parentheses cause FileNotFoundError and UI crash during import

EDIT Special characters on import are showing this behavior not only parentheses!.

Describe the bug

Album folders with parentheses in their name (e.g. (1986) Duotones or Innocence (2023))
cause a JavaScript crash in the import UI: can't access property "asis_candidate", o is undefined.
The backend also throws a FileNotFoundError when attempting to list the directory, suggesting
parentheses in folder names are not being escaped or handled correctly in path resolution.

Expected behavior

Album folders with parentheses in their names should import correctly through the beets-flask
UI without errors.

To Reproduce

1. Place an album folder with parentheses in its name into the inbox (e.g. (1986) Duotones or Innocence (2023))
2. Open beets-flask in the browser (http://localhost:5001)
3. Navigate to the import section and select the album folder
4. Wait for MusicBrainz matching to complete
5. See error: can't access property "asis_candidate", o is undefined

Workaround

Renaming the folder to remove parentheses (e.g. Duotones, Innocence) resolves the issue
and allows the import to proceed normally.

Technical Details

Two folders confirmed to trigger the issue:

• /music/inbox/(1986) Duotones — parentheses at the start of the name
• /music/inbox/Innocence (2023) — parentheses at the end of the name

The backend log shows the directory cannot be listed for either folder, and the watchdog
attempts to start the handler twice before failing:

[INFO] beets-flask.wdog: Watchdog: Starting inbox handler task /music/inbox/(1986) Duotones
[INFO] beets-flask.wdog: Watchdog: Starting inbox handler task /music/inbox/(1986) Duotones
could not list directory /music/inbox/(1986) Duotones
Traceback (most recent call last):
  File "/usr/local/lib/python3.11/site-packages/beets/util/__init__.py", line 223, in sorted_walk
    contents = os.listdir(syspath(bytes_path))
FileNotFoundError: [Errno 2] No such file or directory: '/music/inbox/(1986) Duotones'

could not list directory /music/inbox/Innocence (2023)
Traceback (most recent call last):
  File "/usr/local/lib/python3.11/site-packages/beets/util/__init__.py", line 223, in sorted_walk
    contents = os.listdir(syspath(bytes_path))
FileNotFoundError: [Errno 2] No such file or directory: '/music/inbox/Innocence (2023)'

Frontend stack trace:

ii@http://localhost:5001/assets/folder_._path._hash-Cwmrjl_y.js:3:35845
lf@http://localhost:5001/assets/index-xm4Iat20.js:9:48430
Af@http://localhost:5001/assets/index-xm4Iat20.js:9:71300
bv@http://localhost:5001/assets/index-xm4Iat20.js:9:81689
Xv@http://localhost:5001/assets/index-xm4Iat20.js:9:117555
Uw@http://localhost:5001/assets/index-xm4Iat20.js:9:116595
Qf@http://localhost:5001/assets/index-xm4Iat20.js:9:116423
Vv@http://localhost:5001/assets/index-xm4Iat20.js:9:113196
hy@http://localhost:5001/assets/index-xm4Iat20.js:9:125193
Ra@http://localhost:5001/assets/index-xm4Iat20.js:9:123739
ly@http://localhost:5001/assets/index-xm4Iat20.js:9:124019
q2/Qw/<@http://localhost:5001/assets/index-xm4Iat20.js:9:125251

• beets-flask version: v1.2.1 (backend and frontend)
• Running via: Docker
• Mode: prod
• Screenshots: none

[keratomalaciant]

Having the same issue right now, but my folder doesn't have parentheses, its called "Dreamcast Summer Songs - Devon Hendryx" and i still get the same error, maybe its for all special symbols?

[JoaoSobral]

You probably right. Try to remove the "-" and see if it works properly

[keratomalaciant]

Yep, it does, i removed the dash and it imported successfully.

[JoaoSobral]

Perfect, i have updated the bug on the top to mention special characters._

[pSpitzner]

Hey guys, thanks for the detailed triage and workaround.

We will make sure to fix the escaping bug for the 2.0 release!
(As always, feel free to open a PR)

best,
p

Edit: Can you confirm this problem still persists with the 2.0rc? I tried to reproduce it here (based on 2.0rc) and could not.