Server guides · Troubleshooting
Why Audiobookshelf keeps logging you out
Update to Audiobookshelf v2.36.0 or later first; it fixed several causes of repeated logouts. Then check token settings, the sign-in rate limit and fail2ban.
Start with your server version. Audiobookshelf v2.35.0, v2.35.1 and v2.36.0 fixed several causes of repeated logouts. Update to v2.36.0 or later before trying workarounds from older issue comments.
If you’re on a current version and still get logged out, check when it happens and what the server log says. An expired session, a password change, the sign-in rate limit, a ban from fail2ban and a failing proxy can all interrupt access. The app’s message and the server log tell them apart.
SoundLeaf does not support API key login. Some other apps offer one to avoid these logouts. In SoundLeaf you sign in with a username and password, or with OpenID.
How long does an Audiobookshelf session last?
When you sign in, the server gives the app two tokens. The access token is a short pass the app sends with every request. The refresh token lasts longer, and the app uses it to get a new access token when the old one runs out. Each time, the server also hands out a new refresh token and retires the old one.
The defaults in v2.36.0 and later are below. The 1 hour and 30 day values arrived in v2.31.0, and the grace period in v2.36.0.
| Setting | Default | What it does |
|---|---|---|
ACCESS_TOKEN_EXPIRY | 1 hour (3600) | How long an access token works |
REFRESH_TOKEN_EXPIRY | 30 days (2592000) | How long a refresh token works, so how long a device can go unused |
REFRESH_TOKEN_GRACE_PERIOD | 10 minutes (600) | How long a retired refresh token still works (since v2.36.0) |
All three are in seconds and set as environment variables on the server. The official environment page still lists the older defaults of 43200 and 604800. The server code uses the values above.
If a device goes 30 days without renewing, its session ends. SoundLeaf can usually sign in again by itself for password accounts (see below). With the default settings, regular use while connected to the server renews the session.
What changed in v2.36.0
v2.36.0 (July 27, 2026) fixed a case where a lost reply during renewal ended the session for good (#5281). It also changed what signs you out on purpose:
- 10 minute grace period. A retired refresh token now works for 10 minutes, up from 1 minute. If a phone lost the reply, went to the background or switched networks, it can still recover by trying again within those 10 minutes.
REFRESH_TOKEN_GRACE_PERIODchanges it. - A password change signs out other sessions. Changing your own password ends your sessions on every other device; the one you changed it from stays signed in. An admin changing your password ends all your sessions. Each app then has to sign in with the new password.
- Sessions list and Logout All Devices. The account page in the web page now lists your sessions, lets you end one, and has a Logout All Devices button. If you pressed it, every app has to sign in again.
Is Audiobookshelf blocking too many sign-in attempts?
Since v2.26.0, Audiobookshelf limits sign-in requests from each IP address. By default that’s 40 requests in 10 minutes. It counts password sign-ins, OpenID sign-ins and the requests apps make to renew a session. Past the limit, the server answers “Too many authentication requests” until the window passes.
RATE_LIMIT_AUTH_MAXsets the number of requests.0turns the limit off.RATE_LIMIT_AUTH_WINDOWsets the window, in milliseconds (default 600000, 10 minutes).
If your reverse proxy (the server that passes outside requests on to Audiobookshelf) doesn’t pass the visitor’s real IP address (X-Forwarded-For or X-Real-IP), every device behind it shares one count. Several phones and browser tabs can then use up 40 quickly. Pass the real IP, or raise the limit.
On the sign-in screen, SoundLeaf shows “Too many requests. Please wait a moment and try again.” When renewing a session in the background, SoundLeaf waits and tries again later instead of signing you out.
Could fail2ban be blocking your phone?
fail2ban is a tool that reads log files and blocks an IP address after too many failed sign-ins. Since v2.26.0, an app gets a 401 Unauthorized answer when its access token has run out, and then renews it. With a 1 hour access token, that can happen about once an hour for every device in use. A fail2ban filter that counts 401 answers in your proxy log sees failed logins that aren’t, and can block your own phone’s IP address. That looks like a logout, or like the server went offline.
Fix: count only real failed sign-ins. Audiobookshelf writes those to its own log as [LocalAuth] Failed login attempt for username "name" from ip ..., which is a better line to match than proxy 401s. Or add your home IP addresses to fail2ban’s ignore list. A user asked about this in the v2.26.0 discussion. The maintainer explained that renewing after a 401 is normal, but gave no fail2ban settings.
Check that the server keeps its data after updates
Sessions live in the server’s database. If the server log shows database write errors, check the /config volume and its permissions. Back up the configuration before moving it. Keep the SQLite database on local storage; the audiobook files can live elsewhere. One user in the original investigation reports that moving the config folder to an Unraid exclusive share fixed their unresponsive server and repeated sign-ins.
If your container gets replaced on update, make sure /config is a mounted volume (a folder on the host computer that the container uses). A config folder inside the container is lost with it, and so is every session.
Should I make the tokens last longer?
Usually not. Older comments suggest raising ACCESS_TOKEN_EXPIRY to work around bugs that v2.35.0 to v2.36.0 fixed. A longer access token stays usable longer if it leaks. If phones that sit unused for weeks are the problem, raising REFRESH_TOKEN_EXPIRY is the safer change.
Could Cloudflare or your reverse proxy cause logouts?
Several reports in the original issue came from servers behind a Cloudflare Tunnel. A proxy that times out or drops a reply while the app renews its session can cause a logout. The 10 minute grace period in v2.36.0 gives the app more time to recover from that.
If you use Cloudflare Access with a service token, SoundLeaf includes the token headers in its requests to your Audiobookshelf server. If requests start failing, check that the token hasn’t expired, and that the Service Auth policy (the Cloudflare rule that lets the service token through) still covers it. See Cloudflare Access setup.
To tell a proxy problem from a session problem, open the same server address in Safari and try the web page. If the local address works while the remote one fails, check the proxy response and certificate. The reverse proxy guide covers the connection settings between your proxy and Audiobookshelf. A Tailscale connection can help rule out the public proxy, but it won’t repair an expired session by itself.
When reporting a problem, include the server and app versions, whether it also happens in the web page, and a redacted log excerpt. Remove full access and refresh tokens before sharing logs.
How SoundLeaf handles an expired session
SoundLeaf remembers your sign-in and can usually reconnect password accounts automatically. When the access token runs out, SoundLeaf uses the refresh token to get a new one. If the server refuses that too, SoundLeaf signs in again by itself with the saved username and password, and carries on.
That can’t work in these cases, and then the account shows Sign in again:
- The password changed, or the account was removed or disabled.
- No password is saved for the account on this device.
- The account uses OpenID. There’s no saved password, so you sign in through your provider again. See Sign in to SoundLeaf with OpenID.
To reconnect, open Settings > Servers, tap Accounts under the right server, pick the account and tap Sign in again. The screen says “Sign in again to reconnect this account. Your saved content is still available.”
If the server can’t be reached at all, SoundLeaf doesn’t sign you out. It tries again later. Fix the connection first.
Which Audiobookshelf versions fixed logout problems?
Audiobookshelf introduced access and refresh tokens in v2.26.0. Before v2.36.0 (covered above), these releases changed it:
- v2.31.0, December 1, 2025: defaults changed to 1 hour and 30 days.
- v2.35.0, May 17, 2026: a 1 minute grace period lets a retired refresh token work briefly (PR #5004).
- v2.35.1, May 28, 2026: two sessions renewing in the same second no longer get identical tokens (#5253, PR #5255).
The original tracking issue has the investigation and older workarounds. Check which release has a fix before applying a workaround from an older comment.