Category: Supabase and databases

Supabase: Refresh Token Expired — Troubleshooting

Read this guide in Polish

This document describes in detail the case when an application using Supabase starts returning authorization errors related to refresh of the session: e.g. 401/403 when trying to use a fresh token, log-in interrupted after a short time or no refresh after rebooting the server. I do not assume one reason: I have prepared a list of possible sources of the problem (customer configuration, supabase-side expiry policy, leaks/key changes, cookie/local implementation errorsStorage, problems with proxy or CORS). For each variant I specify how to test it clearly and what to improve. The instructions are practical: you will perform them in a development and production environment without the risk of losing user data.

How to Recognize Cause

See if the problem is just about fresh tokens or the whole flow auth. Use the network console in your browser or curl tool to call endpoint /auth/v1/token with grant type=refresh token and follow the answer. If the server returns 401 with an invalid token message, it is likely that the token expired or was cancelled on the Supabase side.

Verify the JWT configuration and expire policy (JWT expiri) in the Supabase panel: if the fresh token was awarded with a short TTL or the 'Enable Fresh Token Rotation' option has been changed, then there is a scenario that rotation invalidated the previous token. Also check that the service key or anon/public key has not been reset — this cancels the sessions.

Do not miss the client layer: errors in writing a fresh token to cookie (HttpOnly, path, domain, security), or overwriting localStorage/sessionStorage can cause the application to send an outdated token. For server applications, check if you do not use multiple SubbaseClient instances with different settings.

Step by step solution

1. Log in with the test account and save the access token and refresh token values from the answers /auth/v1/token. Follow POST /auth/v1/token request with grant type=refresh token using curl: curl -X POST 'https://<project>.supabase.co/auth/v1/token' -d 'grant type=refresh token&refresh token=<token>' and save the answer and the code HTTP.

2 . If the request returns 200, compare the issue time and expires in in response to what the SDK client does. Make sure SDK receives and retains both tokens — do not overwrite fresh token new access token. For SDK JS, check supabase.auth.getSession() and supabase.auth.onAuthStateChange().

3 . If the request returns 401 or 400 with the reason 'invalid grant' or 'token revoked', check in the Supabase panel: there was no key rotation (Project Settings -> API -> Keys) or manual deregistration of the session. Change the service key cancels the sessions — play the session after generating new keys.

4 . Check the refresh rotation policy: if rotation is enabled, each refresh prints a new fresh token and cancels the previous one. Test the flow sequentially: perform 2 more refreshes using the same token — the other should be rejected. If a parallel application calls refreshy, add lock/mutex to execute it sequentially.

5 . For SSR or proxy applications: check that the cookie with fresh token is not shortened by the proxy (SameSite, path, domain). In devtools check the presence of HttpOnly cookie and its value after server reboot. For Next.js/Node, make sure that the SSR reads and writes cookies from the same domain view.

6 . If you use JWT custom or external provider OAuth, make sure callbacks correctly map and save refresh token. In the case of providers (Google, GitHub) sometimes refresh token is only issued on first authorisation — test full flow OAuth and log in the received tokens.

7 . If the problem occurs irregularly, enable request/response login on refresh (only in the test environment) and compare trace-id/headers. Check that the proxy or CDN does not cache the endpoint auth — endpoints of authorization should not be cached.

How to see if the problem is gone

Test 1: Manual fresh by curl should return 200 and new access token and fresh token (if rotation is enabled). Repeat the immediate re-use of the old refresh token — if rotation it works, the second call should return the error.

Test 2: Play production scenario: log out and log in again, then restart backend/SSR and try to perform an operation requiring a refreshed session. Monitor server logs: if the application sends a valid current refresh token, the operation should go without 401.

Test 3: Simulate parallel refreshs — call up several simultaneous refresh requests with the same token. If the application does not serialize a refreshy, expect only the first one to pass; after fixing all requests should benefit from one sequential refresh process.

What to do

Do not log or refresh token in production logs; only log status and trace-id. Token leaks allow you to take over the session.

Do not expect fresh token to last forever — check TTL and rotation policy instead of assuming inexhaustibility.

Avoiding serialization of refresh operations (parallel refreshy) is a common cause of sudden rejection of tokens at rotation — apply mux/queue.