SoundLeaf

SoundLeaf Logo
All Docs Troubleshooting

Connection Troubleshooting

Fix common connection issues when connecting to your Audiobookshelf server

Having trouble connecting SoundLeaf to your Audiobookshelf server? This guide covers the most common issues and solutions.

Before You Start

Test your server URL in Safari first. If it doesn’t work in the browser, it won’t work in SoundLeaf.

Common Issues

”Connection failed” on login screen

Most likely cause: Wrong protocol (HTTP vs HTTPS)

With no protocol on the front, SoundLeaf tries HTTPS first and falls back to HTTP. That works, but the failed HTTPS attempt has to time out first, and some hosts drop the connection instead of refusing it. Naming the protocol yourself is quicker and more reliable:

✗ audiobookshelf.local:13378
✗ 192.168.1.100:13378
✓ http://audiobookshelf.local:13378
✓ http://192.168.1.100:13378

Always include http:// or https:// explicitly.

URL verified but login fails

  1. Check credentials - Username and password are case-sensitive
  2. Check the login method - If your server has OpenID (SSO) turned on, use the OpenID button rather than the username and password fields. A server set to OpenID only has no local password to type.
  3. Server version - Very old Audiobookshelf versions may have compatibility issues. Update to the latest version.

Works locally but not remotely

Your server needs to be accessible from the internet. Options:

”Error loading library” after login

This usually means:

  • The library is empty
  • API compatibility issue with your server version

Try selecting a different library, or check that the library has content. Book and podcast libraries both work, and you can switch between them from Settings → Library or by pressing and holding the tab bar.

Server Configuration Issues

Behind a Reverse Proxy

If using nginx, Caddy, or similar:

  1. Ensure WebSocket support is enabled (required for real-time sync)
  2. Check that the proxy passes the correct headers
  3. Verify SSL certificate is valid (not self-signed, unless you’ve configured trust)

nginx example:

location / {
    proxy_pass http://localhost:13378;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Self-Signed Certificates

SoundLeaf doesn’t trust self-signed SSL certificates by default. Options:

  1. Use HTTP instead (fine for local network or VPN)
  2. Get a free SSL certificate from Let’s Encrypt
  3. Use Cloudflare as a proxy (free SSL)

Cloudflare Access / Zero Trust

If your server is behind Cloudflare Access, you need to configure service token headers. See our Cloudflare Access setup guide.

Network-Specific Issues

Corporate/School WiFi

Some networks block non-standard ports or certain traffic. Try:

  1. Using port 443 (standard HTTPS port) for your server
  2. Connecting via mobile data to test
  3. Using a VPN

IPv6

If your server is IPv6-only, ensure your network supports IPv6. Most mobile networks do, but some WiFi networks don’t.

Still Not Working?

  1. Check server logs - Your Audiobookshelf server logs may show what’s failing
  2. Update everything - Make sure both SoundLeaf and Audiobookshelf are on the latest versions
  3. Report the issue - If nothing works, open an issue on GitHub with your server setup details