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.

Users on the tracking issue report being kicked out 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. ABS invalidates all JWT sessions for that user when the username changes. 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 several users reported improvement after these changes, particularly 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.

A few users reported logouts continued even over Tailscale, so this isn’t always enough on its own.

How SoundLeaf handles this on iPhone

SoundLeaf stores your credentials in the iOS Keychain when you first log in. When the server rejects a refresh token, the app uses those stored credentials to get a fresh session in the background instead of dropping you on the login screen.

In order, on a 401 the app:

1. Tries to refresh the token.
2. If the refresh fails, re-authenticates with the stored credentials.
3. Retries the original request.

You only see the login screen if the server is genuinely unreachable or your password actually changed. If constant re-logins on other clients are wearing you down, give SoundLeaf a try. The getting started guide walks through it.

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.