[BUG] replaygain plugin is not working as expected

[mcurly]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

These come up on the full docker logs:

      
      ██║     ██╔════╝██║██╔═══██╗

      ██║     ███████╗██║██║   ██║

      ██║     ╚════██║██║██║   ██║

      ███████╗███████║██║╚██████╔╝

      ╚══════╝╚══════╝╚═╝ ╚═════╝

   Brought to you by linuxserver.io

───────────────────────────────────────

To support LSIO projects visit:

https://www.linuxserver.io/donate/

───────────────────────────────────────

GID/UID

───────────────────────────────────────

User UID:    1000

User GID:    1000

───────────────────────────────────────

Linuxserver.io version: 2.6.2-ls313

Build-date: 2026-02-22T16:19:33+00:00

───────────────────────────────────────

    

**** Adding ffmpeg to OS package install list ****

**** Adding beets-filetote to pip install list ****

[pkg-install-init] **** Installing all mod packages ****

(1/9) Installing py3-setuptools-pyc (80.9.0-r2)

(2/9) Installing py3-pip-pyc (25.1.1-r1)

(3/9) Installing py3-packaging-pyc (25.0-r0)

(4/9) Installing py3-parsing (3.2.5-r0)

(5/9) Installing py3-parsing-pyc (3.2.5-r0)

(6/9) Installing py3-packaging (25.0-r0)

(7/9) Installing py3-setuptools (80.9.0-r2)

(8/9) Installing py3-pip (25.1.1-r1)

(9/9) Installing python3-dev (3.12.12-r0)

Executing busybox-1.37.0-r30.trigger

OK: 503.8 MiB in 249 packages

[pkg-install-init] **** Installing all pip packages ****

WARNING: The directory '/config/.cache/pip' or its parent directory is not owned or is not writable by the current user. The cache has been disabled. Check the permissions and owner of that directory. If executing pip with sudo, you should use sudo's -H flag.

Requirement already satisfied: pip in /lsiopy/lib/python3.12/site-packages (26.0.1)

Collecting wheel

  Downloading wheel-0.46.3-py3-none-any.whl.metadata (2.4 kB)

Requirement already satisfied: setuptools in /lsiopy/lib/python3.12/site-packages (82.0.0)

Requirement already satisfied: packaging>=24.0 in /lsiopy/lib/python3.12/site-packages (from wheel) (26.0)

Downloading wheel-0.46.3-py3-none-any.whl (30 kB)

Installing collected packages: wheel

Successfully installed wheel-0.46.3

WARNING: The directory '/config/.cache/pip' or its parent directory is not owned or is not writable by the current user. The cache has been disabled. Check the permissions and owner of that directory. If executing pip with sudo, you should use sudo's -H flag.

Looking in links: https://wheel-index.linuxserver.io/alpine-3.23/

Collecting beets-filetote

  Downloading beets_filetote-1.3.1-py3-none-any.whl.metadata (28 kB)

Requirement already satisfied: beets<2.7.0,>=2.4.0 in /lsiopy/lib/python3.12/site-packages (from beets-filetote) (2.6.2)

Requirement already satisfied: mediafile>=0.12.0 in /lsiopy/lib/python3.12/site-packages (from beets-filetote) (0.14.0)

Requirement already satisfied: confuse>=2.2.0 in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (2.2.0)

Requirement already satisfied: jellyfish in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (1.2.1)

Requirement already satisfied: lap>=0.5.12 in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (0.5.12)

Requirement already satisfied: numpy>=2.0.2 in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (2.4.2)

Requirement already satisfied: packaging>=24.0 in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (26.0)

Requirement already satisfied: platformdirs>=3.5.0 in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (4.9.2)

Requirement already satisfied: pyyaml in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (6.0.3)

Requirement already satisfied: requests-ratelimiter>=0.7.0 in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (0.9.1)

Requirement already satisfied: typing_extensions in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (4.15.0)

Requirement already satisfied: unidecode>=1.3.6 in /lsiopy/lib/python3.12/site-packages (from beets<2.7.0,>=2.4.0->beets-filetote) (1.4.0)

Requirement already satisfied: filetype>=1.2.0 in /lsiopy/lib/python3.12/site-packages (from mediafile>=0.12.0->beets-filetote) (1.2.0)

Requirement already satisfied: mutagen>=1.46 in /lsiopy/lib/python3.12/site-packages (from mediafile>=0.12.0->beets-filetote) (1.47.0)

Requirement already satisfied: pyrate-limiter~=4.0 in /lsiopy/lib/python3.12/site-packages (from requests-ratelimiter>=0.7.0->beets<2.7.0,>=2.4.0->beets-filetote) (4.0.2)

Requirement already satisfied: requests>=2.20 in /lsiopy/lib/python3.12/site-packages (from requests-ratelimiter>=0.7.0->beets<2.7.0,>=2.4.0->beets-filetote) (2.32.5)

Requirement already satisfied: charset_normalizer<4,>=2 in /lsiopy/lib/python3.12/site-packages (from requests>=2.20->requests-ratelimiter>=0.7.0->beets<2.7.0,>=2.4.0->beets-filetote) (3.4.4)

Requirement already satisfied: idna<4,>=2.5 in /lsiopy/lib/python3.12/site-packages (from requests>=2.20->requests-ratelimiter>=0.7.0->beets<2.7.0,>=2.4.0->beets-filetote) (3.11)

Requirement already satisfied: urllib3<3,>=1.21.1 in /lsiopy/lib/python3.12/site-packages (from requests>=2.20->requests-ratelimiter>=0.7.0->beets<2.7.0,>=2.4.0->beets-filetote) (2.6.3)

Requirement already satisfied: certifi>=2017.4.17 in /lsiopy/lib/python3.12/site-packages (from requests>=2.20->requests-ratelimiter>=0.7.0->beets<2.7.0,>=2.4.0->beets-filetote) (2026.1.4)

Downloading beets_filetote-1.3.1-py3-none-any.whl (25 kB)

Installing collected packages: beets-filetote

Successfully installed beets-filetote-1.3.1

[custom-init] No custom files found, skipping...

** error loading plugin replaygain

Traceback (most recent call last):

  File "/lsiopy/lib/python3.12/site-packages/beetsplug/replaygain.py", line 1250, in __init__

    self.backend_instance = BACKENDS[self.backend_name](

                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

  File "/lsiopy/lib/python3.12/site-packages/beetsplug/replaygain.py", line 574, in __init__

    raise FatalReplayGainError(

beetsplug.replaygain.FatalReplayGainError: replaygain.command must be one of {'mp3gain', 'mp3rgain', 'aacgain'}, not ''

During handling of the above exception, another exception occurred:

Traceback (most recent call last):

  File "/lsiopy/lib/python3.12/site-packages/beets/plugins.py", line 470, in _get_plugin

    return obj()

           ^^^^^

  File "/lsiopy/lib/python3.12/site-packages/beetsplug/replaygain.py", line 1254, in __init__

    raise ui.UserError(f"replaygain initialization failed: {e}")

beets.ui.UserError: replaygain initialization failed: replaygain.command must be one of {'mp3gain', 'mp3rgain', 'aacgain'}, not ''

 * Serving Flask app 'beetsplug.web'

 * Debug mode: off

WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.

 * Running on http://127.0.0.1:8337

Press CTRL+C to quit

Connection to localhost (127.0.0.1) 8337 port [tcp/*] succeeded!

[ls.io-init] done.

Expected Behavior

No errors or warnings shown.

Steps To Reproduce

This is my current docker-compose.yaml file:

(only the volume-names are redacted)

services:
  beets:
    image: lscr.io/linuxserver/beets:latest
    container_name: beets
    environment:
      - DOCKER_MODS=linuxserver/mods:universal-package-install
      - INSTALL_PACKAGES=ffmpeg
      - INSTALL_PIP_PACKAGES=beets-filetote
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Lisbon
    volumes:
      - /path/to/config:/config
      - /path/to/music/library:/music
      - /path/to/music/to/catalogue:/downloads
    ports:
      - 8337:8337
    restart: unless-stopped

Environment

It is this proxmox virtual machine:

"Linux docker 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 GNU/Linux"

This is the host:

"Linux pve 6.17.9-1-pve #1 SMP PREEMPT_DYNAMIC PMX 6.17.9-1 (2026-01-12T16:25Z) x86_64 GNU/Linux"

CPU architecture

x86-64

Docker creation

Please, see above

Container logs

Again, above, please, thank you.

[thespad]

As it says

beets.ui.UserError: replaygain initialization failed: replaygain.command must be one of {'mp3gain', 'mp3rgain', 'aacgain'}, not ''

e.g.

replaygain:
    command: mp3gain

The shipped default config includes the correct replaygain settings, but we aren't going to go fiddling with people's existing configs to make them compliant.

[mcurly]

replaygain:
command: mp3gain
The shipped default config includes the correct replaygain settings, but we aren't going to go fiddling with people's existing configs to make them compliant.

Correct.

Thank you for having presented the solution.

I apologize for this. Although I don't know yet what did I do to have the replaygain plugin configuration wrong. I am almost certain that the error was not there before. But not absolutely sure, which means that there is a great chance that I did get it wrong in the first place.

Either way, thank you for your correction!

@thespad ☀️

Can close this now.

[thespad]

I think it's an upstream change as we didn't have it in the configs originally, but added it a few weeks ago when the errors cropped up in our CI smoke tests.