Supabase refresh_token_already_used: Refresh token has been revoked and falls outside the refresh token reuse interval

What it means in plain English

refresh_token_already_used means the refresh token has been revoked and falls outside the refresh token reuse interval. Supabase's sessions guide says a refresh token can only be used once. The reuse interval is 10 seconds by default, and Supabase does not recommend changing it.

Two cases are allowed inside that design. Server-side rendering may need the same refresh token on the server and soon after on the client. If the client never received the response, using the parent of the currently active refresh token returns the active token. Outside those cases, Supabase regards the whole session as terminated and revokes its refresh tokens.

A different code, refresh_token_not_found, means the session containing the refresh token was not found. conflict is the code for too many session refresh requests at the same time.

Likely causes

• Two parts of the app refreshed the same token, and the second call landed outside the 10-second reuse interval.
• The client retried a refresh after missing the response, and that retry was also outside the interval.
• The access token's JWT expired line is the short-lived access token, which is a different code. See Supabase error: JWT expired.

How to fix it, step by step

1. Read error.code. refresh_token_already_used is a revoked refresh token. Sign the user in again. A session is created when a user signs in.
2. Make one refresh at a time for that session. Supabase's conflict code is the one it documents for concurrent refresh requests, and it says to back off exponentially when you find that.
3. On a server-rendered app, keep the server refresh and the following browser refresh inside the reuse interval. The sessions guide names that server-then-client case as a reason the interval exists.
4. The sessions guide says you can turn this reuse check off under Advanced Settings on the Auth settings page, and that doing so is generally not recommended.
5. If the first query runs before the session exists, that is a timing problem. See Supabase data loads only after a refresh.

How to check it worked

• One tab, one refresh, and the call returns a new access token and refresh token.
• A second refresh that reuses the token you just exchanged, after the reuse interval, is the failure. A new sign-in starts a new session.

Sources

• https://supabase.com/docs/guides/auth/debugging/error-codes (opens in a new tab)
• https://supabase.com/docs/guides/auth/sessions (opens in a new tab)