Skip to content
SoundLeaf
App Store
Menu

Server guides

Running your Audiobookshelf server

Setting up Audiobookshelf on Docker, Linux or a NAS, putting it behind a reverse proxy, and fixing the problems people run into most. Troubleshooting guides are listed newest first.

Setup

16 guides

  1. Audiobookshelf Docker quickstart: setup and first login

    Start Audiobookshelf with Docker, create your admin account, add a book library and find the server URL to use on your iPhone.

  2. Set up Audiobookshelf with Docker Compose

    Run Audiobookshelf with Docker Compose, the method the official docs recommend: the compose file, what each folder holds, first setup and safe updates.

  3. Install Audiobookshelf on Linux without Docker

    Install Audiobookshelf without Docker: the official package for Debian and Ubuntu, a community RPM for RHEL and Rocky Linux, or the NixOS service.

  4. Audiobookshelf on Synology, Unraid & TrueNAS

    Install Audiobookshelf on popular NAS platforms: Synology DSM, Unraid, and TrueNAS

  5. What port does Audiobookshelf use?

    Audiobookshelf uses port 13378. In Docker the container listens on port 80, and the usual mapping 13378:80 puts it on 13378 on your computer.

  6. Is there an official Audiobookshelf iPhone app?

    Not on the App Store. The official Audiobookshelf iPhone app is a TestFlight beta that is often full. Here's how seats free up, sideloading, and other apps.

  7. Audiobookshelf folder structure: one folder per book, series, and why books merge

    Give every book its own folder, like Author/Series/Title. An audio file sitting in a parent folder pulls the books below it into one item. Here are the rules.

  8. Move your audiobooks from Plex to Audiobookshelf

    Point Audiobookshelf at the folders Plex already uses and run both side by side. Listening progress doesn't carry over, so mark finished books in bulk.

  9. Audible to Audiobookshelf with Libation or OpenAudible

    Point Libation or OpenAudible at your Audiobookshelf library folder, save M4B files with chapters, and new Audible purchases show up in Audiobookshelf.

  10. Ebooks and audiobooks as one book in Audiobookshelf (and Send to Kindle)

    Put the EPUB in the same folder as the audiobook and Audiobookshelf shows one book with both. Plus primary ebooks, Audiobooks only, and Send to Kindle.

  11. Podcasts in Audiobookshelf: add a show, auto-download episodes and keep only the latest

    Audiobookshelf downloads podcast episodes to your server first. Only admins add shows. Set auto-download and how many episodes to keep on each show.

  12. Listen to Audiobookshelf away from home: Tailscale, reverse proxy or Cloudflare Tunnel

    Just you? Use Tailscale. Family who won't install a VPN? Use a domain with a reverse proxy and HTTPS, or a Cloudflare Tunnel. How to pick, and the common traps.

  13. Audiobookshelf reverse proxy: Nginx, Caddy and HTTPS setup

    Put Audiobookshelf behind Nginx, Caddy, Nginx Proxy Manager, Apache, HAProxy or Traefik with HTTPS and WebSockets, plus fixes for 413 and socket errors.

  14. Audiobookshelf with a Cloudflare Tunnel: setup, 502 errors and app sign-in

    Run cloudflared next to Audiobookshelf and point the tunnel at http://audiobookshelf:80. Fixes for 502 and 522, app sign-in with Access, and upload limits.

  15. Audiobookshelf users and permissions: share with family, limit what kids see

    Give each person their own Audiobookshelf user, then limit what they see by library, by tag or by the Explicit flag. What each account type and permission does.

  16. How to secure your Audiobookshelf server

    A practical guide to securing a self-hosted Audiobookshelf server: HTTPS, rate limiting, Cloudflare Access or Tailscale, Docker permissions, API keys, and backups.

Troubleshooting

28 guides

  1. Why Audiobookshelf keeps logging you out

    Update to Audiobookshelf v2.36.0 or later first; it fixed several causes of repeated logouts. Then check token settings, the sign-in rate limit and fail2ban.

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

    Fix Audiobookshelf startup crashes after an upgrade: remove working_dir for the /index.js error, and update or roll back for the 2.37 EACCES and EPERM errors.

  3. New audiobooks getting the wrong metadata in Audiobookshelf

    Fix the bug where newly added audiobooks steal metadata from existing books due to inode collisions on NAS and network shares

  4. Audiobookshelf stops playing between chapters on iOS

    Why audiobook playback stops at the end of each track on iOS Safari and how to fix it with single-file M4B books or a native app

  5. Audiobookshelf audio goes silent after the first chapter

    Fix M4B audiobooks that play Chapter 1 fine then go silent when the channel count or sample rate changes between chapters

  6. Audiobookshelf stops working after a reboot

    Fix Audiobookshelf failing to load or stream books after rebooting a Docker host by making Docker wait for your external drive or NAS mount.

  7. Running Audiobookshelf as a non-root user in Docker

    Fix EACCES permission denied errors when running Audiobookshelf Docker with user: 1000:1000 by pre-creating config and metadata directories

  8. Audiobookshelf OpenID login errors and fixes

    Fix Audiobookshelf OpenID login errors: check X-Forwarded-Proto, the issuer URL, user matching and sign-in timeouts. Each error with its cause and fix.

  9. Why seeking in Audiobookshelf jumps back to the start

    Seeking a podcast or large single-file audiobook resets playback to the start in mobile Audiobookshelf apps. Why it happens and how to fix the file.

  10. Audiobookshelf won't add new books to your library

    A library scan that quietly adds nothing is usually one book with a duplicate author tripping a database constraint. Here's how to find and fix it.

  11. Audiobookshelf won't recognize xHE-AAC audiobooks from Libation

    Why Audiobookshelf skips xHE-AAC (USAC) m4b files from Libation, and how to fix it with a Docker update or your own ffmpeg binaries.

  12. Audiobookshelf progress jumped back or got lost: causes and fixes

    Audiobookshelf progress jumps back when an app sends an old position or a book becomes a new item. Find your spot in Listening Sessions and stop it recurring.

  13. Audiobookshelf "Socket failed to connect": causes and fixes

    "Socket failed to connect" usually means your reverse proxy blocks WebSocket traffic. Fixes for Nginx, Nginx Proxy Manager, Apache, Caddy, Traefik and HAProxy.

  14. Audiobookshelf works in the browser but the iPhone app can't connect

    If Audiobookshelf opens on the server but not in your iPhone app, it's usually the address, the iPhone's Local Network setting, or the server's firewall.

  15. Audiobookshelf downloads are slow away from home

    Away from home, downloads can't beat your home internet's upload speed. How to check Tailscale relays, tunnels and mobile data, and download at home.

  16. Audiobookshelf can't see my audiobook folder (Docker, Windows, Mac)

    In Docker, Audiobookshelf only sees folders you map into its container. Map your audiobook folder to /audiobooks, recreate the container, then pick /audiobooks.

  17. Audiobookshelf library empty after a Docker update (and moving to a new computer)

    Check that the new container still uses your old /config, /metadata and book folders. Anything that was never mapped went with the old container.

  18. Which audiobook formats play on iPhone with Audiobookshelf

    MP3 and M4B with AAC are the safe formats for iPhone. Audiobookshelf can convert others while streaming, but downloads are always the original file.

  19. Audiobookshelf metadata matching: Match vs Quick Match and fixing wrong titles or chapters

    Match lets you pick a result and the details to keep; Quick Match takes the first result and fills gaps. Plus fixes for wrong titles, chapters and series.

  20. Forgot your Audiobookshelf password? How to reset it (and the default login)

    Audiobookshelf has no default password. An admin resets a user's password in Settings > Users. A lost root password means editing the database.

  21. Audiobookshelf series in the wrong order: sequence numbers that sort correctly

    Audiobookshelf sorts a series by the number at the start of each book's sequence. Use plain numbers or decimals like 3.01, and no spaces, so books sort right.

  22. Continue Listening and Continue Series in Audiobookshelf: what they show and why a book is stuck there

    Continue Listening shows started books you haven't finished. Continue Series offers the next book. Why a finished book stays, duplicates, and how to hide one.

  23. Why Audiobookshelf adds /audiobookshelf to your URL, and the 'Dangerous site' warning

    Since v2.18.0 the Audiobookshelf web page moves to /audiobookshelf. Apps aren't affected. Plus what to do when Google flags your server as a dangerous site.

  24. Audiobookshelf crashes with JavaScript heap out of memory

    Why adding a podcast episode to an Audiobookshelf playlist crashes the server with a JavaScript heap out of memory error, and how to work around it.

  25. Audiobookshelf won't import books from LibbyRip

    Why Audiobookshelf scans fail or skip LibbyRip-ripped audiobooks, and how to fix the metadata.json so the books show up.

  26. Audiobookshelf still shows books after I deleted them from disk

    Why Audiobookshelf keeps removed files as 'missing' items and how to clear them using the Issues filter in the web client

  27. Audiobookshelf crashes after a quick match and won't stay up

    Fix the SequelizeUniqueConstraintError on bookSeries that crashes Audiobookshelf into a Docker restart loop after a quick match

  28. Why Audiobookshelf library scans take hours on network storage

    Fix slow Audiobookshelf scans on CIFS, SMB, NFS, and NAS setups caused by transient inode values triggering unnecessary ffprobe re-scans