You reboot your Raspberry Pi, Ubuntu server, or NAS, and Audiobookshelf comes back broken. The container shows as running in docker ps, the logs look normal, but the web UI hangs for 30 seconds and then times out. Or it loads, but trying to stream a book throws errors. A manual docker compose down && docker compose up -d fixes it instantly, and then it works fine until the next reboot.

The cause is Docker starting before your audiobook drive finishes mounting. When the Audiobookshelf container initializes, it looks for /audiobooks, /config, and /metadata. If those paths point to an external USB drive, a SMB share, or an NFS mount that hasn’t come up yet, the container sees empty directories and runs against nothing. Restarting works because by then the drive has mounted.

Issue #4308 has reports from Raspberry Pi 4B (Ubuntu 24.04), AMD x86 hosts with SMB-mounted audiobooks, and exFAT-formatted external SSDs. A contributor confirmed the root cause: “Your file system may not be available/mounted before the docker container starts when booting the raspberry pi.”

The error in your logs often looks like this when you try to play or download a book:

ERROR: [LibraryItemController] Failed to download file "/Book - 002.mp3" Error: write EPIPE
    at afterWriteDispatched (node:internal/stream_base_commons:161:15)
    at writeGeneric (node:internal/stream_base_commons:152:3)
    at Socket._writeGeneric (node:net:958:11)
    ...
  errno: -32,
  code: 'EPIPE',
  syscall: 'write'
}

Or you may see nothing obviously wrong in the startup logs at all. The container runs, says Listening on http://0.0.0.0:80, and just doesn’t serve content properly.

The fix: make Docker wait for your mount

The cleanest solution is a systemd drop-in that tells docker.service to wait for your audiobook mount before starting. This was confirmed working by a user on a Pi 4B with an exFAT-formatted SSD.

First, make sure your drive is in /etc/fstab with a stable mount point. If you’re mounting ad-hoc or only on demand, systemd has nothing to coordinate against. A typical fstab line looks like this:

# /etc/fstab
UUID=1234-5678  /media/audiobooks  exfat  defaults,nofail  0  0

The nofail flag is important. It prevents boot from hanging forever if the drive is missing.

Then create a drop-in config for the Docker service:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/wait-for-mounts.conf

Paste this, replacing the path with wherever your audiobooks actually live:

[Unit]
RequiresMountsFor=/media/audiobooks

If you have multiple mounts (say, audiobooks and podcasts on different drives), list them all:

[Unit]
RequiresMountsFor=/media/audiobooks /media/podcasts /mnt/config

Reload systemd and reboot to test:

sudo systemctl daemon-reload
sudo reboot

After the reboot, check the drive is mounted before Docker started:

systemctl status docker | head -5
mount | grep audiobooks

If Docker started after the mount showed up, you’re done.

If RequiresMountsFor doesn’t work

RequiresMountsFor relies on systemd generating a .mount unit for your fstab entry. Most filesystems work, but some network mounts (especially CIFS/SMB with weird options) don’t generate one reliably. If you still get the same symptoms after adding the drop-in, reference the mount unit explicitly.

Find the mount unit name:

systemctl list-units --type=mount | grep audiobooks

You’ll get something like media-audiobooks.mount (systemd replaces / with -). Then update your drop-in:

[Unit]
After=media-audiobooks.mount
Requires=media-audiobooks.mount

Requires= fails Docker if the mount unit fails, which is usually what you want. If you’d rather Docker start anyway and serve an empty library rather than not start at all, use Wants= instead of Requires=.

If your mount is a network share

SMB and NFS shares are trickier because the network has to be up before the share can mount. Add _netdev to your fstab options so systemd knows to wait for network-online.target:

# /etc/fstab
//nas.local/audiobooks  /media/audiobooks  cifs  _netdev,credentials=/etc/smbcreds,nofail  0  0

Then your Docker drop-in should also wait for the network:

[Unit]
After=network-online.target media-audiobooks.mount
Requires=network-online.target media-audiobooks.mount

If your network mount still fails to come up in time, switch to on-demand mounting with x-systemd.automount. This mounts the share lazily when something first accesses it, and it plays well with Docker starting early:

//nas.local/audiobooks  /media/audiobooks  cifs  _netdev,x-systemd.automount,credentials=/etc/smbcreds,nofail  0  0

If that didn’t work

A few things worth checking:

Docker’s own delay. Docker has its own startup dependencies, and at least one user reported the issue surfacing right after a Docker engine update. Try sudo systemctl restart docker as a quick test right after boot before touching the stack. If that alone fixes it, your mount is fine and Docker itself is starting against stale state.

Compose file paths are wrong. If your docker-compose.yml uses relative paths like ./audiobooks:/audiobooks and you run docker compose up from a directory whose parent isn’t mounted yet, you get the same symptom. Use absolute paths to your mount point instead: /media/audiobooks:/audiobooks.

The container was created before the fix. The drop-in only affects container startup ordering, not a container that was created against an empty mount. After adding the drop-in, recreate the container once to get clean state:

docker compose down
docker compose up -d

Then reboot and test.

Affected setups

This isn’t tied to a specific Audiobookshelf version. It affects any Docker host where:

• Your audiobooks, config, or metadata directory lives on an external drive, USB SSD, SMB share, or NFS mount
• That mount isn’t guaranteed to be ready before docker.service starts
• Common culprits: Raspberry Pi with external USB drives, Ubuntu/Debian servers mounting a NAS, x86 hosts with Docker Compose stacks whose data lives off the boot drive

If your audiobooks live on the same drive as your OS, you won’t hit this.