supabase auth refresh token not found: session expiry handling

supabase auth refresh token not found: session expiry handling

TL;DR

The refresh token is gone: expired, revoked, or never persisted, so the session cannot renew. Treat it as a signed-out state: clear local session and route to login. Also fix the cause: persist refresh tokens reliably and do not let them expire silently.

AuthApiError: refresh token not found

Steps

1. Handle it as signed-out: clear the local session and redirect to login. Expected: The app recovers gracefully.

2. Check refresh-token persistence: is it stored reliably (httpOnly cookie or secure storage) and sent on refresh? Expected: The storage path is verified.

3. Check the refresh token's lifetime settings in Supabase; expired tokens cannot refresh. Expected: The lifetime is known.

4. Fix the persistence or lifetime issue found above. Expected: Refresh works for live sessions.

5. Distinguish this from network errors in the client: only this error means re-login. Expected: The UX routes correctly.

When to use

• Supabase sessions die with refresh-token-not-found
• after storage changes
• refresh lifetimes were adjusted

When not to use

• the error is intermittent (check the network first)
• the token exists but is rejected (different error)
• using a custom auth backend (Supabase-specific handling)

Tool compatibility

• Supabase Auth
• GoTrue

Variant phrasings

• "supabase refresh token not found"
• "supabase session expiry handling"
• "refresh token not found supabase auth"

Why it happens

Refresh tokens are the durable half of the session; when they vanish, there is nothing to renew with. Causes range from aggressive storage clearing to expired lifetimes to revoked sessions. The client must treat it as signed-out, because from the server's perspective the session is over.

Edge cases

• clearing site data wipes refresh tokens; that is working as designed
• the re-login UX should preserve the user's intended destination
• server-side session revocation is a feature; handle it, do not fight it

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bCiNl9nYrtkpg6w59vNznA

Resolved from the public thread: https://vectle.com/posts/pst_bCiNl9nYrtkpg6w59vNznA

Thread query: supabase auth refresh token not found: session expiry handling

TL;DR: The refresh token is gone: expired, revoked, or never persisted, so the session cannot renew. Treat it as a signed-out state: clear local session and route to login. Also fix the cause: persist refresh tokens reliably and do not let them expire silently.