Audiobookshelf "Socket failed to connect": causes and fixes

“Socket failed to connect” means the live connection to Audiobookshelf couldn’t open. The most likely cause is a reverse proxy that isn’t passing WebSocket traffic, so start by turning on WebSocket support in your proxy (the setting for each one is below).

The socket is a live connection the web app and the phone apps keep open, so the server can tell them about changes right away: new progress, new books, edited playlists. The Audiobookshelf web app only connects it as a WebSocket, so a proxy that doesn’t allow the upgrade to WebSocket breaks it every time.

What the messages mean

Audiobookshelf’s web app shows these at the bottom of the page:

• “Socket failed to connect”: it tried to open the live connection and couldn’t.
• “Socket disconnected”: the connection was open and then dropped. It keeps trying to reconnect.
• “Socket connected”: it’s back.

Playback in the web app often still works when the socket fails, because the audio itself comes through ordinary requests. Live updates break, and so can playback that needs the server to convert the audio first, because the web app hears when that stream is ready over the socket.

First check: does it happen on the local address?

Open the server on its local address, like http://192.168.1.20:13378, from a computer on your home network.

• No message on the local address: the proxy is the likely problem. Find yours below.
• The message shows there too, or the page doesn’t load: look at the server first. Skip to the server isn’t running properly.

Turn on WebSockets in Nginx

Add the WebSocket headers to your location block and reload Nginx:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Nginx versions before 1.29.7 talk to the server over HTTP/1.0 unless you set proxy_http_version 1.1, and HTTP/1.0 can’t upgrade to a WebSocket. Keep the line on newer versions too; it does no harm. The full config is in the reverse proxy guide.

Turn on WebSockets in Nginx Proxy Manager

Edit the proxy host and turn on Websockets Support on the Details tab. It’s off for new hosts.

Turn on WebSockets in Apache

On Apache 2.4.47 and newer, add upgrade=websocket to the ProxyPass line. On older versions, turn on mod_proxy_wstunnel and add rewrite rules that send WebSocket requests to ws://. Both versions are in the reverse proxy guide.

Check WebSockets through Caddy

Caddy passes WebSockets through reverse_proxy with no extra settings. If you see the message with Caddy:

• Check that nothing else in the site block rewrites or filters responses. In issue #3913, one user’s socket broke because of a theme add-on that changed the page through a filter. Removing the filter fixed it.
• One user fixed it by adding a separate route for /audiobookshelf/socket.io/*. Others with the same setup said it didn’t help, so try the simple config first.

Check WebSockets through Traefik

Traefik also passes WebSockets with no extra settings. Look at any extra rules (Traefik calls them middlewares) attached to Audiobookshelf. A sign-in service in front of the whole site, such as Authelia or Authentik forward auth, stops apps, because apps can’t show its sign-in page. Remove it or bypass it for Audiobookshelf, and use Audiobookshelf’s own OpenID sign-in if you want single sign-on.

Keep WebSockets open in HAProxy

HAProxy upgrades WebSocket connections on its own in HTTP mode. What it needs is a timeout for open WebSockets, or it closes them early. Add this to the Audiobookshelf backend:

timeout tunnel 1h

HAProxy’s WebSocket guide has a full example.

Check WebSockets through Cloudflare

If your domain goes through Cloudflare (orange cloud or a tunnel), WebSockets are supported on every plan. Check that the WebSockets switch on your domain’s Network page is on.

Cloudflare closes WebSockets that sit idle for a while and when it restarts its servers. Audiobookshelf reconnects by itself, so an occasional “Socket disconnected” is normal. In issue #4329, one user found that after leaving a tab in the background for a couple of minutes, Cloudflare showed a 525 SSL error page instead of letting the socket reconnect. That’s a user report, not something Cloudflare documents. More on tunnels in the Cloudflare Tunnel guide.

Allow app connections through Pangolin

Pangolin can put its own sign-in page in front of Audiobookshelf. That’s a web page, and the apps’ live connection can’t fill it in. Leave Pangolin’s sign-in off for Audiobookshelf, or add a Bypass Auth rule for it. Audiobookshelf still asks for its own username and password.

Why does Audiobookshelf disconnect every two minutes?

If “Socket disconnected” comes back on a steady timer, something is closing the connection on that timer. In issue #5434, the socket dropped about every two minutes behind Nginx. The cause turned out to be a broken scheduled task that restarted Nginx every two minutes. Check for scheduled jobs and the proxy’s own timeouts before blaming the server.

The server isn’t running properly

If the message also shows on the local address, look at the server.

Audiobookshelf broke after a reboot

When Audiobookshelf starts before your audiobook drive or network share is mounted, it can come up half working. Once the drive is mounted, restarting the container usually brings it back, until the next reboot. Audiobookshelf stops working after a reboot shows how to make Docker wait for the drive.

Synology: the container listens on port 3333 after an update

In issue #3868, Synology users who updated with Container Manager couldn’t reach the server at all, and the log said Listening on port :3333 instead of :80. The Docker image tells Audiobookshelf to use port 80. When that setting doesn’t reach the server, Audiobookshelf falls back to port 3333, so your port mapping points at nothing.

Keep a backup from Audiobookshelf’s backup settings first. The fix from that thread: stop the container, choose Action > Reset in Container Manager, then start it again. It should log Listening on port :80. When updating later, use Reset rather than the upgrade option.

The proxy only forwards part of the site

The socket has its own path on the server: /audiobookshelf/socket.io (and /socket.io, which some apps use). If your proxy forwards only some paths to Audiobookshelf, or runs it under a folder with a different name, the page loads but the socket goes nowhere. Forward the whole site. If you use a folder, use /audiobookshelf, the path the web app is built for.

Does this affect playback in SoundLeaf?

No. SoundLeaf plays, downloads and saves your progress with ordinary requests, so a blocked socket doesn’t stop listening.

SoundLeaf uses the socket while the app is open, for live updates: progress you made on another device, and changes to your account and playlists, show up straight away. Without it, those changes don’t arrive the moment they happen.

At the top of Settings, the line under your server address shows Live when that connection is up. If it stays on Reconnecting while books still play fine, the live connection can’t get through, and the checks above are where to look. If your proxy needs custom headers, such as a Cloudflare Access service token, SoundLeaf sends them on the live connection too.