Why Mobile Apps Randomly Log You Out: The Token Refresh Bug Behind the Spinner

Archi4 min read

mobilesecurityengineeringdebugging

Contents
  1. The Spinner That Shouldn't Be There
  2. Clock drift: the quiet killer
  3. Concurrency: five requests, one refresh token
  4. Network flakiness and the retry that never comes
  5. The retry storm after a 401
  6. What good looks like
  7. Why it ships anyway

The Spinner That Shouldn't Be There#

You open a banking app, tap the balance tab, and get a login screen. No password change, no new device, no warning. You log in again, and everything works. Two days later it happens again. Support calls this "session management." The engineering root cause is usually narrower: the token refresh path has a race condition, a clock problem, or a network failure that the app handles badly.

Most mobile apps today use short-lived access tokens (often 15 to 60 minutes) and longer-lived refresh tokens (days to months). The access token goes on every API call. When it expires, the app calls a refresh endpoint with the refresh token, gets a new pair, and retries the original request. That flow has three points where it can break: time, concurrency, and connectivity.

Clock drift: the quiet killer#

Tokens carry an exp claim, and servers check it against their own clock. Phones are not always right. A device that has been off for a week, crossed time zones on a flight with airplane mode on, or had its network time sync blocked can drift by minutes or hours. If the phone thinks it is 10:03 but the server thinks it is 10:19, the app may send a token it believes is still valid while the server rejects it as expired. Worse, the app may refresh too early, burning through refresh tokens faster than the server expects.

Some apps use the device clock to decide when to refresh, adding a safety margin like 60 seconds. That works until the margin is smaller than the drift. A common fix is to parse the exp value from the token and compare it to the server's Date header, not the local clock, but many SDKs skip that step because it adds a network round trip or because the header is stripped by a proxy.

Concurrency: five requests, one refresh token#

When a screen loads, it often fires several API calls at once: user profile, account list, notifications, feature flags. If the access token has just expired, all five calls fail with 401. A naive client triggers five refresh requests in parallel. The server, enforcing refresh token rotation, accepts the first and invalidates the others. Four calls fail permanently. The user sees a logout.

The fix is a single-flight refresh: one coroutine or dispatch queue owns the refresh, and other calls await its result. Many teams implement this on iOS with an actor and on Android with a mutex. When it is missing, the bug appears intermittently, usually on cold starts or after the phone wakes from sleep, which is exactly when several background tasks resume at once.

Network flakiness and the retry that never comes#

Mobile networks drop. A refresh request that times out mid-flight leaves the client in an ambiguous state. Did the server rotate the token? If the client retries with the old refresh token, and the server already invalidated it, the user is logged out. If the client does not retry, the session stalls.

Some backends solve this by allowing a short grace window on the old refresh token, accepting it once more within, say, 30 seconds. Others issue a new refresh token only after the client confirms receipt. Both add complexity, and both are often missing in first versions.

The retry storm after a 401#

A subtler bug appears when the app retries the original request after refreshing. If the retry logic reuses a stale token variable captured before the refresh, the retry sends the old token again and gets another 401. Some clients then loop, refreshing repeatedly until the server rate-limits them. The user experiences a long spinner followed by a logout. Logs show a burst of refresh calls, which looks like abuse but is just a variable scope bug.

What good looks like#

A solid refresh implementation has four properties:

  1. Server time, not device time. The client uses the token's exp and the response Date header to decide when to refresh, and tolerates small drift.
  2. Single-flight refresh. One refresh at a time, with other requests queued behind it.
  3. Idempotent retries. The original request is retried with the new token, and the retry reads the token from shared storage, not a local copy.
  4. Grace on rotation. The server accepts the previous refresh token briefly, so a lost response does not force a logout.

None of these are exotic. They are the difference between an app that logs you out every few days and one that quietly keeps working. When a user complains about random logouts, the question to ask is not whether the session expired. It is which of the four properties above is missing.

Why it ships anyway#

The bug survives because it is intermittent. In QA, devices have accurate clocks, stable Wi-Fi, and one request at a time. In the field, users have old phones, spotty coverage, and background sync. The failure rate is low enough to pass a launch review and high enough to generate support tickets for years. Teams that instrument refresh failures separately from other 401s tend to find it fast. Teams that lump all auth errors together keep shipping the same bug.

More articles