Audiobookshelf won't start after an upgrade (Docker, Debian, TrueNAS)

For Cannot find module '/index.js' after upgrading, remove the old working_dir setting and recreate the container. For EACCES on the Debian or Ubuntu package with 2.37.0, update to 2.37.1. For the EPERM crash loop on TrueNAS with 2.37, roll back to 2.36.1. Both 2.37 problems are in the 2.37 section further down.

Cannot find module ‘/index.js’ after upgrading to 2.22.0 or later

In v2.22.0, Audiobookshelf changed the Docker image’s working directory from / to /app (the Dockerfile change). If your container or management tool cached the old working_dir, the 2.22.0 startup command node index.js looked for /index.js instead of /app/index.js and crashed immediately.

The error in your logs looks like this:

Error: Cannot find module '/index.js'
    at Module._resolveFilename (node:internal/modules/cjs/loader:1212:15)
    at Module._load (node:internal/modules/cjs/loader:1043:27)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:164:12)
    at node:internal/main/run_main_module:28:49 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}
Node.js v20.19.1

This affects Synology, Portainer, Cosmos Cloud, plain docker-compose, and anything else that caches container settings. If you were upgrading from 2.21.0, going back to it works for the moment, but the real solution is removing the stale working_dir. There are multiple threads about this on GitHub (#4292, #4309, #4289).

The image also got smaller because curl and other tools were removed. If you had a healthcheck using curl, that breaks too.

The fix: remove working_dir and recreate

Check your docker-compose file or container settings for a working_dir entry and remove it. Leave everything else, including all your volume lines, as it is.

# BEFORE - this breaks v2.22.0+
services:
  audiobookshelf:
    image: advplyr/audiobookshelf:latest
    working_dir: /          # <-- DELETE THIS LINE
    volumes:
      - ./config:/config
      - ./metadata:/metadata
      - ./audiobooks:/audiobooks

# AFTER - let the image use its own default (/app)
services:
  audiobookshelf:
    image: advplyr/audiobookshelf:latest
    volumes:
      - ./config:/config
      - ./metadata:/metadata
      - ./audiobooks:/audiobooks

After removing working_dir, you need to fully recreate the container, not just restart it. The old container has the cached working directory baked in.

docker compose down
docker compose up -d

If you didn’t explicitly add working_dir yourself, it might have been set automatically by your management tool. Check Portainer’s Command & logging tab under Advanced container settings, or Cosmos Cloud’s compose editor.

Recreate the container in Synology, Portainer or Cosmos Cloud

Synology Container Manager

Restarting keeps the old container settings. The official Docker guide says to stop the container, then choose Reset under Actions. Reset deletes anything that isn’t in a mapped folder, so check your volumes first.

For a Container Manager project, you can also:

1. Stop the container
2. In Container Manager, right-click the project and select Clean
3. Rebuild the project

If that doesn’t work, delete the container entirely (don’t delete your volumes/data) and create a new one pointing to the same volumes.

Portainer

If you run Audiobookshelf as a Portainer stack, open the stack’s editor, delete the working_dir line and click Update the stack.

If you run it as a single container:

1. Open the container and click Duplicate/Edit
2. Under Advanced container settings, open Command & logging
3. Set both Command and Entrypoint to Default
4. Clear the Working Dir field (leave it blank)
5. Click Deploy the container, then Replace

If you can’t find the working_dir setting, try a trick a contributor posted on #4292 that forced Portainer to reset. Temporarily add these lines to your compose and recreate. Then remove them and recreate again:

entrypoint: ["/bin/sh", "-c"]
command: ["ls && tail -f /dev/null"]

Cosmos Cloud

Remove the working_dir entry from the Cosmos compose editor. If the editor also lists NUSQLITE3_DIR or NUSQLITE3_PATH environment variables, remove those too. A Cosmos user fixed the crash this way, and a contributor confirmed they’re safe to drop from the compose file, because the image sets its own. Cosmos modifies compose files internally and can cache stale values.

Fix your healthcheck too

If your container was using a curl-based healthcheck (Docker’s regular check that the server is answering), it’ll fail now because curl was removed from the image. Switch to wget:

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://127.0.0.1/healthcheck"]
  interval: 1m
  timeout: 10s
  start_period: 30s

If nothing works: pull a fresh image and recreate the container

If you’ve tried everything above and it still crashes:

# Stop and remove the container
docker compose down

# Remove the cached image
docker rmi advplyr/audiobookshelf:latest

# Pull fresh and start
docker compose pull
docker compose up -d

Your data is safe as long as your volumes are properly mounted (config, audiobooks, metadata directories). Removing the image and container doesn’t touch mounted volumes.

If even that doesn’t work and you were upgrading from 2.21.0, pin to that version while you troubleshoot:

image: advplyr/audiobookshelf:2.21.0

Don’t stay on an old version long-term. You’ll miss security patches. The real fix is removing working_dir.

Which versions this affects

It only hits a container that still carries the old working_dir: / setting, when it moves from 2.21.0 or older to 2.22.0 or newer. A fresh install that uses the image’s default working folder won’t hit this.

Audiobookshelf 2.37 won’t start after the move to Node.js 24

v2.37.0 (released September 28, 2026) moved the server and the Docker image to Node.js 24, the engine Audiobookshelf runs on. The Docker image brings its own copy, so you don’t install anything. Two startup crashes followed on some setups.

”EACCES: permission denied, mkdir ‘/home/audiobookshelf’” (Debian and Ubuntu package)

This hit the Debian and Ubuntu package (the apt install), not Docker. 2.37.0 tried to write to a home folder the audiobookshelf user never had, and the service stopped at start (#5613).

It’s fixed in v2.37.1, released the next day. The fixed service gives the server a folder of its own to write to. Update:

sudo apt update
sudo apt upgrade audiobookshelf

If the service still won’t start after a few failed tries, run sudo systemctl reset-failed audiobookshelf and then sudo systemctl start audiobookshelf. To go back to the old version instead, run sudo apt install audiobookshelf=2.36.1.

”EPERM: operation not permitted, copyfile” crash loop on TrueNAS

The container starts, fails and restarts over and over. The log shows:

ERROR: [Database] Failed to run migrations Error: Failed to copy migrations to the config directory.
  [cause]: [Error: EPERM: operation not permitted, copyfile '/app/dist-server/server/migrations/v2.15.0-series-column-unique.js' -> '/config/migrations/v2.15.0-series-column-unique.js']
FATAL: [Server] Unhandled rejection: Error: Database migration failed

This is #5637, open as of October 17, 2026. The reports share the same setup: TrueNAS SCALE, /config on a ZFS dataset (a storage area in a TrueNAS pool), and the container running as a user without admin rights, usually 568 (the TrueNAS apps user). It happens with the TrueNAS community app and with plain Docker on TrueNAS. It starts with 2.37.0.

People testing on the issue report that the folder permissions are fine: the same user can create files in /config, and the same copy worked in the 2.36.1 image, which ran Node.js 20. They suspect the way Node.js 24 copies files is refused on that kind of mount. That isn’t confirmed, and no fix has been released yet.

To get running again, go back to 2.36.1. Copy your config and metadata folders somewhere safe first. Reporters on the issue say their database was fine after rolling back.

• TrueNAS community app: go back to app version 1.6.14, which runs Audiobookshelf 2.36.1. App version 1.6.18 (Audiobookshelf 2.37.1) still crash-loops, according to the issue.

• Docker, Dockge or Portainer: pin the image to the old version and recreate the container:

  image: ghcr.io/advplyr/audiobookshelf:2.36.1
  

  docker compose up -d
  

If you use automatic updates, pause them for Audiobookshelf until #5637 is fixed, or they’ll install the broken version again. Check the issue before you move back to latest.

For other permission errors in Docker, see running Audiobookshelf as a non-root user.

Before your next upgrade

An upgrade that stops at startup is easier to undo when you have a recent backup and know your old version. Library empty after a Docker update covers safe updates and backups.