Fix guide · updated 2026-11-15
Supabase "Invalid Refresh Token: Refresh Token Not Found"
Invalid Refresh Token: Refresh Token Not Found · refresh_token_not_found · Invalid Refresh Token: Already Used · AuthApiError
Your app logs people out at random, or a user comes back after a while and lands on the login page. The browser console shows AuthApiError: Invalid Refresh Token: Refresh Token Not Found (newer versions of supabase-js print it as a warning, not an error). Supabase isn't down. The session that the browser remembers no longer exists on the server. Here's why that happens and how to make it harmless.
What the error means
A Supabase session is two tokens: an access token that lasts 1 hour by default, and a refresh token. Before the access token runs out, supabase-js trades the refresh token for a new pair. Supabase's docs put it simply: refresh tokens never expire, but each one can only be used once.
We read the check in the source code of Supabase Auth (internal/tokens/service.go). It answers refresh_token_not_found with "Invalid Refresh Token: Refresh Token Not Found" when the token the browser sends isn't in the database at all. It isn't expired or reused: it's gone. Two related messages come from the same check:
refresh_token_already_used, "Invalid Refresh Token: Already Used": the token was already traded more than 10 seconds earlier (cause 4 below).session_expired, "Invalid Refresh Token: Session Expired": a session limit set in the dashboard ran out (cause 5).
Either way, supabase-js treats the session as dead. It drops it from that device (recent versions wait until the current access token runs out) and your app receives a SIGNED_OUT event. If your app doesn't react to that event, the user sees a half-logged-in screen, empty data or a blank page.
Why the refresh token is gone
1. The user changed their password on another device
Changing a password signs the user out of every other session. In Supabase Auth's code, the password update logs out all sessions except the current one. The phone or laptop that stayed open finds out at its next refresh, within the hour.
2. They logged out somewhere else
supabase.auth.signOut() uses scope: 'global' by default: it ends every session of that user, on every device. If your "Log out" button should only log out the device it's on, pass the scope:
await supabase.auth.signOut({ scope: 'local' });
3. You deleted the user or reset the database while testing
This one is very common while building. You delete test users in the Supabase dashboard, or rebuild the database, while a browser tab still holds the old session. The sessions went away with the user. Nothing to fix in the code: clear the site's data in that browser, or log in again.
4. Two refreshes fought over the same token
Supabase allows a refresh token to be used a second time only within 10 seconds of its first use. Its docs call this the reuse interval and advise against changing it. A second use after that window looks like a stolen token, so Supabase revokes the whole session and every later refresh fails.
The usual cause in AI-built apps is createClient() called in several files. Each copy keeps its own refresh timer on the same stored session. supabase-js warns about this in the console: "Multiple GoTrueClient instances detected in the same browser context. It is not an error, but this should be avoided as it may produce undefined behavior when used concurrently under the same storage key." A tab that was asleep for a long time and wakes up with an old token can trigger the same thing.
5. The session hit a limit you set
On Pro plans and up, Supabase can end sessions after a fixed time, after a period of inactivity, or keep only one session per user (Authentication → Sessions). Those end with a "Session Expired" message. The limit is checked at the next refresh, so a session can last the limit plus up to one access-token lifetime.
Fix 1: handle it like a normal logout
Whatever the cause, the user has to sign in again. Make that clean: listen for the sign-out once, where your app starts, and send the user to your login page.
// Run once, where you create the Supabase client or in App.tsx
supabase.auth.onAuthStateChange((event) => {
if (event === 'SIGNED_OUT') {
// Clear your own copy of the user (context, store, cached data)
window.location.assign('/login');
}
});
Don't keep your own copy of the user in localStorage and trust it later. Read the session from Supabase (supabase.auth.getSession() or the event above), so your screens follow what Supabase knows.
Fix 2: one Supabase client for the whole app
Create the client in one file and import it everywhere else. Lovable projects already have that file at src/integrations/supabase/client.ts. The trouble starts when a later prompt adds a second createClient() in a component or a hook.
// src/lib/supabase.ts: the only place that calls createClient in browser code
import { createClient } from '@supabase/supabase-js';
export const supabase = createClient(
import.meta.env.VITE_SUPABASE_URL,
import.meta.env.VITE_SUPABASE_ANON_KEY
);
// everywhere else
import { supabase } from '@/lib/supabase';
Search your project for createClient(. In browser code it should appear once. Edge functions and other server code are separate and don't count. Also remove any timer that calls supabase.auth.refreshSession() by hand: the client already refreshes on its own.
Fix 3: if your app renders on a server
With Next.js and @supabase/ssr, the session lives in cookies and the server can refresh it. The middleware that refreshes it must send the new cookies back with its response. If it builds a fresh response without them, the browser keeps the old refresh token, which the server has just used. The next refresh then fails as "Already Used" and the session ends. The 10-second reuse interval exists for the normal server-then-browser overlap. It can't save a middleware that never passes the cookies back.
If an AI tool built your app
Lovable, Bolt and similar tools often add a second client or forget the sign-out case. Paste this into your next prompt:
Create the Supabase client in exactly one file and import it everywhere else; remove every other createClient call in browser code. Listen to supabase.auth.onAuthStateChange once: on SIGNED_OUT, clear the user state and redirect to /login. Make the logout button call supabase.auth.signOut({ scope: 'local' }) unless I ask for "log out everywhere". Never call refreshSession on a timer.
Not quite your error?
- Users are signed out after a 429 "Request rate limit reached": Supabase "Request rate limit reached".
- Login fails before any session exists: Supabase auth "Failed to fetch".
- The email link logs the user out instead of in: Supabase "Email link is invalid or has expired".
- Login works locally but sends users to localhost after deploy: Supabase login redirects to localhost.
Still stuck?
Open the Auth logs in your Supabase dashboard at the time of the logout. The failed refresh shows its error code. refresh_token_already_used points to cause 4: look for the "Multiple GoTrueClient instances" warning in the browser console. refresh_token_not_found right after a password change, a logout on another device or a deleted user points to causes 1 to 3, and Fix 1 is all you need. Supabase explains the session rules in its sessions guide.
Other Supabase problems? See Supabase fixes.