fix guide
Supabase Invalid Refresh Token: Refresh Token Not Found
Harjot ·
Your app crashes, or keeps logging people out, and the console says "AuthApiError: Invalid Refresh Token: Refresh Token Not Found". You may also see "Invalid Refresh Token: Already Used".
A refresh token is the saved key that renews a login without asking for the password again. The message means the app tried to renew, and Supabase no longer recognises that key. Seeing it once, followed by a normal login page, is usually harmless. It is a problem when it loops, crashes the page or keeps logging people out. Check these four in order.
1. The login ended on the Supabase side
Supabase's docs say a session lasts indefinitely by default and ends on sign-out, a password change or other security-sensitive actions. Signing out with the default scope signs the user out of every device they are signed in on. A sign-out on a phone kills the saved login on a laptop, and the laptop's next renewal fails with this message.
Supabase also lets you cut sessions short with an inactivity timeout, time-boxed sessions, or a single session per user, which keeps only the most recently active session. The docs say these limits are only available on Pro plans and up. Check your project's Authentication settings for any you turned on.
signs The message shows once after a long break, or after the user signed out on another device, then the login page works normally.
2. Two renewals of the same login
Supabase's docs say a refresh token can only be used once. Each renewal returns a new token. To cover two requests that race, a token can be reused for a short window, 10 seconds by default, and the docs say they do not recommend changing it.
Outside that window, the docs say the whole session is regarded as terminated and all its refresh tokens are revoked. That is the "Already Used" version of the message.
Two renewals happen when your app creates more than one Supabase client, or when the browser and the server both renew. Create the client once, in one file that exports it, and import it everywhere.
signs The message says Already Used, and it shows on page load or when several tabs or requests start together.
3. A saved login for a session that no longer exists
The saved login sits in your browser. If you deleted the user, reset the project's auth data or switched the app to a different Supabase project, the saved login points at a session Supabase cannot find. Supabase's error list describes refresh_token_not_found as "Session containing the refresh token not found."
Clear it once. In Chrome press F12, open the Application tab, choose Storage, and press Clear site data. Then sign in again.
In your code, catch this error and call signOut with the local scope. The docs say that scope signs out only the current session, clears the local session data and triggers the SIGNED_OUT event.
signs Only your own browser shows it, and it started after you deleted users, reset the project or changed which project the app uses.
4. Handle it in the app
Listen for the SIGNED_OUT event with onAuthStateChange. Supabase's docs examples use it to clear stored data. Send the user to the login page there, so a dead login ends on a login screen instead of a broken page. Register the listener right after createClient, as the docs say.
On Next.js, the login is renewed in a proxy file. Supabase's docs say Next.js 16 renamed middleware.ts to proxy.ts, and that on Next.js 15 and earlier a proxy.ts file is never called, so sessions never refresh and users get signed out.
signs The page crashes or reloads in a loop on this error, or the user is logged out on the next click after signing in.
Test it like a new user
- Sign in on one browser, then sign out of the same account on a second browser. Reload the first. You land on the login page with no crash.
- Sign in, then reload the page five times. You stay signed in.
- Open the app in two tabs and reload both at once. Neither logs you out.
- Search your code for createClient. It is called once for the browser.
Common questions
What does Invalid Refresh Token: Refresh Token Not Found mean?
The app tried to renew a saved login and Supabase no longer has that session. The user may have signed out on another device, the session may have ended under your session settings, or the saved login points at data that was deleted. Seeing it once before a normal login page is usually harmless.
What is the difference between Not Found and Already Used?
Not Found means Supabase has no session for that token. Already Used means the token was spent. Refresh tokens work once, with a reuse window of 10 seconds by default. A second renewal outside that window ends the whole session, which usually means the app renewed the same login twice.
How do I stop users being logged out in a loop?
Create the Supabase client once and share it, so only one thing renews the login. Listen for SIGNED_OUT with onAuthStateChange and send people to the login page. On Next.js, check the proxy file is named for your version: proxy.ts on 16, middleware.ts on 15 and earlier.
Still stuck?
Not sure this is the cause? Paste your app's link into the free scan. It lists what a visitor's browser can see, like leaked keys and exposed files, worst first. The score is free; every fix as a prompt for your builder is $9, one-time.
Want a person to look inside? See the diagnosis