# Connection Troubleshooting

> Fix common connection issues when connecting to your Audiobookshelf server

Source: https://soundleafapp.com/docs/connection-troubleshooting/

---

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:

- **Reverse proxy** (nginx, Caddy, Traefik) with SSL
- **Tailscale** - See our [Tailscale setup guide](https://soundleafapp.com/docs/tailscale-vpn-setup/)
- **Cloudflare Tunnel** - See our [Cloudflare Access guide](https://soundleafapp.com/docs/cloudflare-access-setup/)
- **Port forwarding** - Not recommended for security reasons

### "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:**
```nginx
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](https://soundleafapp.com/docs/cloudflare-access-setup/).

## 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](https://github.com/SoundLeaf/SoundLeafApp/issues) with your server setup details