Starting with v2.26.0, Audiobookshelf replaced their permanent API tokens with JWT-based authentication. Access tokens now expire after 1 hour, with a 30-day refresh token to silently get new ones. When that refresh fails, you get kicked to the login screen.

This has caused frequent logouts for a lot of users, sometimes multiple times a day. The root cause varies, but there are a few common culprits and workarounds for each.

The error in your server logs usually looks like this:

[TokenManager] Failed to refresh token. Session not found for refresh token: eyJhbGciOiJIUzI1Ni...

That “Session not found” means the server-side session record for your refresh token is gone. The token itself is fine, but the server can’t find a matching session in its database anymore.

Why sessions disappear

There are a few things that can nuke your sessions:

Your config directory is on network storage. This is the big one, especially on Unraid. If your ABS config directory (which contains the SQLite database) lives on a network share or array drive, the database can get corrupted or lose writes. One user fixed it entirely by moving the config to a local SSD using Unraid’s exclusive shares feature.

An admin changed your username or password. When a username changes, ABS invalidates all JWT sessions for that user. This is by design. The old tokens contain the previous username. But it means every device gets logged out.

The server restarted and the database didn’t flush. If Docker kills the container before SQLite finishes writing, your session records can vanish. This is more common with restart: always on underpowered hardware.

Your reverse proxy is cutting the connection. If you’re running a reverse proxy, check our reverse proxy guide for the recommended setup, and see Fix 2 below.

Fix 1: Move your config to local storage

If you’re on Unraid, Synology, or any setup where the ABS config directory might be on a network mount, move it to a local drive. The SQLite database doesn’t play well with network filesystems.

On Unraid specifically, use an exclusive share pointed at a local SSD:

# In your docker-compose.yml, change the config volume from a share to a direct path
volumes:
  - /mnt/cache/appdata/audiobookshelf:/config  # local SSD, not /mnt/user/
  - /mnt/user/audiobooks:/audiobooks
  - /mnt/user/podcasts:/podcasts
  - /mnt/cache/appdata/audiobookshelf/metadata:/metadata

This was the fix for multiple users in the thread. If your config is already on local storage, skip to the next fix.

Fix 2: Check your reverse proxy timeouts

If you’re running ABS behind Nginx Proxy Manager, Traefik, Caddy, or Cloudflare Tunnels, make sure WebSocket connections aren’t getting killed prematurely.

For Nginx Proxy Manager, add this to your Advanced config:

# Keep WebSocket connections alive
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# Don't let the proxy kill idle connections too early
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;

Also make sure WebSockets Support is enabled in NPM’s settings for the proxy host, and turn off Cache Assets and Block Common Exploits. Those have caused issues for some users. This issue was widely reported after the JWT auth change in v2.26.0.

For Traefik, make sure your middleware isn’t stripping WebSocket headers. The connection between the ABS client and server relies on a persistent socket. If that drops, the client thinks the server is gone.

A note on this fix: A maintainer pointed out that proxy timeouts shouldn’t directly cause token refresh failures. But multiple users reported improvement after these changes, so it’s worth trying, especially if you’re getting disconnected during playback.

Fix 3: Extend token expiry times

If you’re getting logged out because the default 30-day refresh token isn’t long enough (maybe you only listen on weekends), you can increase it:

# In your docker-compose.yml
environment:
  - REFRESH_TOKEN_EXPIRY=7776000  # 90 days in seconds
  - ACCESS_TOKEN_EXPIRY=3600      # 1 hour (default, leave as-is)

Don’t go overboard with the access token expiry. It’s short on purpose for security. The refresh token is the one that matters for “stay logged in” behavior.

Fix 4: Use VPN instead of exposing ABS publicly

Several users noticed the issue is worse when accessing ABS over the internet through a reverse proxy. If you’re using Tailscale or WireGuard to access your server, you can skip the reverse proxy entirely and connect directly. Fewer moving parts, fewer things to break. We have a Tailscale setup guide if you want to go that route.

That said, some users still reported logouts over Tailscale, so this isn’t a silver bullet.

If you’re a SoundLeaf user

SoundLeaf was built with this exact problem in mind. When your access token expires or the server rejects a refresh token, SoundLeaf doesn’t just dump you to a login screen. It silently re-authenticates using your stored credentials (you saved your password once), so SoundLeaf uses it to get a fresh session without interrupting you.

The flow works like this: API call fails with a 401 → SoundLeaf tries to refresh the token → if that fails too, it automatically logs you back in behind the scenes → retries the original request. You keep listening. No login screen, no interruption.

It’ll only show you the login screen if the server is genuinely unreachable or your password changed. And even then, your downloaded books keep playing offline.

If the constant re-logins are driving you nuts on other clients, give SoundLeaf a try. There’s a getting started guide to get you connected in a couple minutes.

Affected versions

This issue affects Audiobookshelf v2.26.0 and later, any version using the new JWT authentication system. Users on v2.29.0+ have reported it most frequently, possibly due to changes in how sessions are managed.

If you’re still on the legacy token system (pre-2.26.0), you won’t hit this issue, but you also won’t get security updates.