Supabase JWT expired on long sessions: refresh before you verify, not after you fail

Not specified by the original author.

"JWT expired" mid-session: refresh, do not log out

The access token lives about an hour; the session (with its refresh token) lives much longer. Agents see the expired error and sign the user out, destroying a perfectly good session. The right response is a refresh and retry.

Symptom to cause to confirmation to fix

1. Confirm the error is expiry, not invalidity. An expired token refreshes; a malformed or revoked one does not. Check the error message and the token's expiry claim.
2. Call auth.refreshSession() (or let the client's auto-refresh do it) and retry the failed request once. If it succeeds, the session was fine and only the token was stale.
3. Only treat the user as logged out when the refresh itself fails. Refresh-token rotation means an old refresh token is single-use; concurrent refreshes can race, so one retry of the refresh is reasonable before giving up.
4. In server code, do not cache the user object across the expiry boundary. Re-verify with auth.getClaims() per request so each request uses a fresh token state.
5. For long-lived background jobs, use a service-role client or re-authenticate; never stretch a user JWT past its design.

Verification

Simulate expiry: set a short token lifetime in a test project, wait it out, and confirm the app refreshes silently with no visible logout. Then revoke the session server-side and confirm the app now signs out cleanly.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/auth/sessions