Supabase "Invalid Refresh Token: Refresh Token Not Found": 3 cause

I tuoi utenti ti scrivono per dirti che sono stati disconnessi. Uno era a metà di un modulo, e un'altra è sicura di non aver toccato niente. Quando provi l'app tu stesso, funziona. Poi apri i log e trovi la stessa riga, ancora e ancora:

AuthApiError: Invalid Refresh Token: Refresh Token Not Found

Supabase "Invalid Refresh Token: Refresh Token Not Found" è Supabase Auth, la parte di Supabase che fa accedere le persone, che dice di non avere traccia del token che la tua app ha inviato per tenere aperta una sessione. Senza più niente da rinnovare, la tua app disconnette l'utente.

Ecco la parte che è facile capire al contrario: questo errore è l'ultimo passo, e la causa è arrivata prima. Quando Supabase non trova più il token, la sessione a cui apparteneva è già finita. L'ha chiusa un logout, un token inviato due volte o un limite che qualcuno ha impostato. Far durare di più l'access token, o spegnere il controllo che chiude una sessione, rende la riga più rara nei log e lascia la causa esattamente dov'era.

Che cosa significa "Invalid Refresh Token: Refresh Token Not Found"?

Significa che Supabase Auth ha ricevuto un refresh token di cui non ha traccia, e quindi si è rifiutato di rinnovare la sessione.

Ogni utente connesso ha due token. L'access token funziona come un braccialetto: dimostra chi è per un po', un'ora se non hai cambiato l'impostazione, e la tua app lo mostra a ogni richiesta. Il refresh token è un biglietto. Prima che il braccialetto scada, la tua app porta il biglietto allo sportello, che è Supabase Auth, e lo cambia con un braccialetto nuovo e un biglietto nuovo. La guida alle sessioni di Supabase dice che i refresh token "never expire but can only be used once".

Refresh Token Not Found è lo sportello che cerca un biglietto e non trova niente. Il server risponde con HTTP 400 e il codice refresh_token_not_found, che l'elenco dei codici di errore di Auth di Supabase descrive come "Session containing the refresh token not found." Se anche il braccialetto è scaduto, il client JavaScript di Supabase toglie la sessione dal browser e comunica alla tua app che l'utente è uscito. È il momento in cui il tuo utente si ritrova davanti alla pagina di accesso.

Nessuno dei due token è una delle chiavi API del tuo progetto, che sono un'altra questione: quali di quelle vanno nella tua app. Se il tuo messaggio dice invece Invalid JWT, è stato rifiutato il braccialetto e non il biglietto, e quell'errore ha una pagina sua. Se poi la persona non riesce a rientrare e il modulo di accesso dice Invalid login credentials, quel messaggio copre tre persone diverse.

Perché i miei utenti Supabase vengono disconnessi?

Perché la sessione dietro il loro biglietto è finita, e il braccialetto che portano ancora li ha tenuti connessi finché non è scaduto. Quel ritardo, fino a un'ora con l'impostazione predefinita, è il motivo per cui le disconnessioni sembrano casuali: l'utente viene buttato fuori un po' dopo la fine della sessione.

Supabase Auth ha quattro modi per dire che un biglietto non vale, e ognuno indica una causa diversa. Questi sono i messaggi esatti presi dal codice del server di Supabase Auth:

Dietro questi messaggi ci sono tre cause, secondo la documentazione di Supabase e le segnalazioni sui suoi issue tracker, e ognuna ha la sua correzione. Se nessuno riesce più ad accedere, o l'intera app è vuota, è un altro problema, e Supabase è giù, o è la tua app? è da dove partire.

Un refresh token funziona una volta

Ogni volta che la tua app rinnova una sessione, consegna il biglietto e lo sportello strappa quello vecchio. Supabase lo chiama rotazione dei refresh token. Il biglietto vecchio funziona ancora per dieci secondi, quello che la guida alle sessioni chiama reuse interval, perché un server e un browser che rinnovano quasi nello stesso momento non si buttino fuori a vicenda. Anche un client che ha cambiato il biglietto e ha perso la risposta per una connessione scadente è coperto: riceve indietro il biglietto attuale.

Fuori da questi due casi, un biglietto vecchio che torna conta come segnale d'allarme, perché un token che si presenta due volte è quello che sembra un token rubato. La guida dice che l'intera sessione "is regarded as terminated and all refresh tokens belonging to it are marked as revoked". La risposta, quella volta, è Already Used.

Un passo in più trasforma Already Used in Not Found. Il server di Supabase Auth cancella le tracce dei biglietti strappati 24 ore dopo la loro revoca. Così il biglietto scaduto che oggi riceve Already Used domani riceve Refresh Token Not Found, perché lo sportello non ha più la traccia con cui confrontarlo.

Causa 1: qualcuno è uscito, su questo dispositivo o su un altro

Un logout cancella la sessione dalla parte dello sportello, e ogni biglietto di quella sessione diventa uno che lo sportello non trova. Nel client JavaScript di Supabase, signOut() senza niente tra le parentesi chiude tutte le sessioni di quell'utente, su tutti i dispositivi. La guida al logout di Supabase lo dice in modo diretto: con quell'impostazione predefinita, le altre sessioni falliscono con AuthApiError: Invalid Refresh Token: Refresh Token Not Found la prossima volta che provano a rinnovarsi, "even though no one signed out on that device."

Così un utente che esce dal telefono viene disconnesso anche sul portatile, fino a un'ora dopo, quando il braccialetto del portatile scade e il suo biglietto torna come sconosciuto. Dal suo punto di vista, la tua app l'ha buttato fuori senza motivo.

Se ogni dispositivo deve restare connesso per conto suo, la chiamata di logout deve chiudere solo la sessione da cui parte:

await supabase.auth.signOut({ scope: 'local' })

Chiedi al tuo builder di usare questa forma ovunque la tua app faccia uscire le persone. L'altro modo comune di chiudere una sessione è un cambio di password, che la guida alle sessioni di Supabase elenca tra le cose che ne chiudono una.

Causa 2: il biglietto nuovo non è mai arrivato al browser

Se la tua app genera le pagine su un server, come fa un'app Next.js, anche quel server rinnova le sessioni. Legge il biglietto da un cookie, lo cambia allo sportello e deve rimandare il biglietto nuovo al browser in un header Set-Cookie della sua risposta. Quando quel cookie non arriva, il browser tiene il biglietto vecchio, e la richiesta successiva presenta un biglietto che il server ha già cambiato. Entro dieci secondi passa. Dopo è Already Used e la sessione finisce, e un giorno dopo lo stesso biglietto è Not Found.

La guida di Supabase per creare un client server nomina l'errore che provoca tutto questo in un'app Next.js. Il codice che rinnova la sessione, che Next.js 16 chiama Proxy e le versioni precedenti middleware, deve restituire la risposta in cui sono stati scritti i cookie nuovi: "An earlier response doesn't carry the refreshed cookies, so the user is signed out on the next request." La stessa guida avverte che in Next.js 15 e precedenti un file chiamato proxy.ts non viene mai eseguito, "so sessions never refresh and users get signed out". Un assistente che lavora con la documentazione più recente può scrivere proprio quel file in un'app più vecchia.

La guida di Supabase dice anche perché questa è difficile da trovare: "it looks like users being signed out at random rather than an error in your code." Le segnalazioni suonano allo stesso modo. Uno sviluppatore ha scritto sull'issue tracker di @supabase/ssr "I'm inadvertently logged out of my web application every day", e l'ingegnere di Supabase che ha risposto ha indicato il modo in cui il middleware passava la sua risposta. La segnalazione di un'app iOS descrive la disconnessione che arriva "2-3 days after logging in", ed è stata chiusa dopo che alcuni aggiornamenti alla libreria Swift di Supabase hanno fatto calare le segnalazioni.

Per controllare, apri gli strumenti per sviluppatori del browser su una pagina che ha rinnovato la sessione e guarda la risposta nella scheda Network. Dovrebbe portare un Set-Cookie con il token nuovo, e la richiesta successiva dovrebbe rimandare indietro quel token.

Causa 3: un limite di sessione nelle impostazioni di Auth

Dal piano Pro in su, Supabase può chiudere le sessioni di proposito, dalla pagina Sessions delle impostazioni di Auth del tuo progetto. Ci sono tre limiti, e la guida alle sessioni li descrive tutti:

• Le sessioni a tempo finiscono dopo un tempo fisso, per quanto l'utente sia attivo.
• Un timeout di inattività chiude una sessione che non viene rinnovata da un po'.
• Una sola sessione per utente tiene solo l'accesso più recente, quindi entrare dal telefono chiude la sessione sul portatile.

Questi lo dicono nel loro messaggio, Session Expired, con (Inactivity) o (Revoked by Newer Login) dopo, per il secondo e il terzo. La guida aggiunge che le sessioni chiuse vengono cancellate 24 ore dopo, quindi un biglietto di una di queste che torna dopo quel termine riceve invece Not Found.

Se hai impostato uno di questi, le disconnessioni sono l'impostazione che fa il suo lavoro. Se non era voluto, o l'ha attivato per te un modello o un assistente, la pagina mostra quale limite è attivo.

Il caso innocuo

Un biglietto di una sessione già finita, che torna da una vecchia scheda o da un browser che nessuno apriva da settimane, riceve anche lui Refresh Token Not Found. La persona dietro era già disconnessa. Il suo browser ha chiesto una volta, Supabase ha detto di no, e lei vede la tua pagina di accesso, cioè quello che avrebbe visto comunque.

In un log appare così: una riga per un utente, spesso poco dopo che quell'utente è uscito da qualche parte, e poi più niente per lui. Righe così sono l'errore che fa il suo lavoro. Quelle da seguire sono le stesse persone di continuo, o tante persone diverse nello stesso giorno.

Come leggere i log di Auth per questo

Apri Logs nella dashboard di Supabase, scegli il tipo di log Auth e cerca refresh token nei messaggi degli eventi. Seleziona una riga per vederne i dettagli, compreso l'ID dell'utente, e il filtro User riduce poi l'elenco a quella sola persona. Quanto indietro vanno i log dipende dal tuo piano, quindi leggili finché le lamentele sono recenti.

Poi leggi che cosa si ripete:

Puoi anche chiedere al database quanto spesso le persone accedono. Ogni accesso aggiunge una riga a auth.sessions, e un logout la cancella. Incolla questo nel SQL Editor:

select user_id, count(*) as sessions, max(created_at) as latest
from auth.sessions
where created_at > now() - interval '14 days'
group by user_id
order by sessions desc
limit 20;

Un utente con molte più sessioni dei dispositivi che ha è entrato di continuo senza mai uscire, ed è quello che fa chi viene buttato fuori dalla tua app in continuazione.

Che cosa non cambiare mentre lo correggi

Le tue regole di Row Level Security, il rilevamento del riutilizzo e la durata dell'access token. Tutti e tre sembrano una correzione e lasciano la causa dov'è, e allentare il primo può aprire i tuoi dati agli sconosciuti.

Lascia stare le tue regole di Row Level Security. Row Level Security è l'insieme di regole che decide quali righe riceve ogni visitatore. Finché gli utenti vengono buttati fuori, ogni schermata la cui regola legge auth.uid() resta vuota per loro, perché secondo la documentazione di Supabaseauth.uid() restituisce null quando la sessione è scaduta. La correzione allettante è allentare quella regola finché la schermata non si riempie di nuovo, e a quel punto si riempie anche per gli sconosciuti. Se qualcuno l'ha già fatto, la nostra scansione gratuita chiede a ogni tabella che la tua app nomina quante righe riceverebbe un visitatore senza login, legge il numero senza scaricare una sola riga e richiede circa 20 secondi, senza account: scansiona la tua app.

Lascia attivo il rilevamento del riutilizzo. Supabase ti permette di spegnerlo, nelle impostazioni avanzate della pagina Sessions, e lo definisce "generally not recommended". Una volta spento, la causa 2 non produce più Already Used, e il biglietto nuovo continua a non arrivare al browser.

Tieni l'access token a un'ora. Un braccialetto più lungo rimanda la disconnessione e lascia la sua causa dov'è. La guida di Supabase dice che impostarlo oltre un'ora è "generally discouraged for security reasons".

Tenere stabili gli accessi dopo la correzione

Due cose possono ancora andare storte quando le disconnessioni si fermano: una modifica successiva le riporta, e una regola allentata lungo la strada lascia una tabella aperta agli sconosciuti.

Reeve Monitor continua a controllare da fuori:

• se la tua app è online, controllato ogni minuto, così un'ondata di messaggi "mi ha disconnesso" non viene scambiata per un guasto
• il controllo di sicurezza completo ogni ora, su un massimo di tre app
• un messaggio quando un risultato cambia, così una regola allentata durante una correzione non aspetta che tu guardi
• un report mensile, in linguaggio semplice, di ciò che ha visto

Reeve Care tiene una copia del tuo database Supabase:

• una copia cifrata secondo una pianificazione, sullo spazio di archiviazione di Reeve nell'UE, fuori dal tuo account Supabase
• lo schema auth in cui vivono gli account dei tuoi utenti, così tornano insieme a tutto il resto
• ogni copia verificata prima che conti, contando le righe di ogni tabella
• anche i tuoi file caricati, appena colleghi una credenziale di Storage
• un ripristino in un clic, con una copia di sicurezza dello stato attuale presa prima
• tutto quello che fa Monitor

Che cosa fare adesso

Comincia dal log di Auth, perché il messaggio che si ripete ti dice quale delle tre cause hai. Poi, quando le persone restano connesse, scansiona la tua app per controllare che niente sia stato allentato lungo la strada.