Supabase error: JWT expired

What it means in plain English

The signed-in user's access token is a JWT with an expiry. Supabase says these tokens are usually valid for 5 minutes to 1 hour. JWT expired means a request used a token past that time. A refresh token can mint a new pair. A refresh token is single-use, with a short reuse window, so refreshing it from two places at once can end the session.

Likely causes

• The app stored the access token and never refreshed it. The default expiry in Auth settings is 1 hour.
• JWT expiry was set under 5 minutes. Supabase says not to go below 5 minutes, and especially not below 2, because the client libraries refresh ahead of time and clocks can be slightly off.
• Server code and the browser both refresh the same token. Supabase's server-side guide says a second refresh terminates the session.
• signOut() was called without a scope. It defaults to global, which revokes every session for that user, including other tabs.

How to fix it, step by step

1. In the dashboard open Auth settings → Sessions. Leave JWT expiry at the default of 1 hour unless you have a reason. Don't set it below 5 minutes.
2. In the browser, use the Supabase client and let it refresh. refreshSession() returns a new session even if the access token is already expired, as long as the refresh token is still valid.
3. In a Next.js app, follow Supabase's server guide: middleware calls getUser() so it refreshes once, writes the new cookies onto the request for Server Components, and writes them onto the response for the browser. Don't also refresh in the page.
4. If you only want to sign out this tab, call signOut({ scope: 'local' }).
5. If the refresh token itself is invalid, the user has to sign in again. That is a new session, not a longer JWT.

How to check it worked

• Stay signed in past the old expiry and load data again. The request should succeed.
• Auth logs should not fill with refresh-token reuse errors after one page load.

Sources

• https://supabase.com/docs/guides/auth/sessions (opens in a new tab)
• https://supabase.com/docs/reference/javascript/auth-refreshsession (opens in a new tab)
• https://supabase.com/docs/guides/auth/server-side/advanced-guide (opens in a new tab)