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

Most likely cause: Wrong protocol (HTTP vs HTTPS)

SoundLeaf defaults to HTTPS if you don’t specify. If your server uses HTTP:

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

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

Check credentials - Username and password are case-sensitive
Check library type - SoundLeaf currently only supports audiobook libraries, not podcast libraries
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:

Reverse proxy (nginx, Caddy, Traefik) with SSL
Tailscale - See our Tailscale setup guide
Cloudflare Tunnel - See our Cloudflare Access guide
Port forwarding - Not recommended for security reasons

This usually means:

You selected a podcast library (not yet supported)
The library is empty
API compatibility issue with your server version

Try selecting a different library, or check that your audiobook library has content.

Server Configuration Issues

Behind a Reverse Proxy

If using nginx, Caddy, or similar:

Ensure WebSocket support is enabled (required for real-time sync)
Check that the proxy passes the correct headers
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:

Use HTTP instead (fine for local network or VPN)
Get a free SSL certificate from Let’s Encrypt
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:

Using port 443 (standard HTTPS port) for your server
Connecting via mobile data to test
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?

Check server logs - Your Audiobookshelf server logs may show what’s failing
Try the demo server - Connect to demo.soundleafapp.com with username demo and password demo to verify the app works
Update everything - Make sure both SoundLeaf and Audiobookshelf are on the latest versions
Report the issue - If nothing works, open an issue on GitHub with your server setup details