[Question]: JWT keeps expiring in background despite alwaysAutoRefresh=true on Supabase 3.1.4

[Yahouedeou]

General info

• I checked the troubleshooting page for similar problems

What is your question?

Problem

I'm experiencing frequent JWT expiration issues in my Android application that primarily runs in the background. Despite configuring alwaysAutoRefresh = true, and enableLifecycleCallbacks = false, sessions aren't consistently refreshed when the app is in background state.

Configuration

I'm using Supabase version 3.1.4 with Kotlin. Here's my client configuration:

val client by lazy {
    createSupabaseClient(
        supabaseUrl = SUPABASE_URL,
        supabaseKey = SUPABASE_KEY
    ) {
        defaultSerializer = KotlinXSerializer(json)
        install(Postgrest)
        install(Realtime)
        install(Auth) {
           alwaysAutoRefresh = true          
           enableLifecycleCallbacks = false
        }
        install(Functions)
    }
}

Questions

• Is there a recommended approach for handling token refreshing in Android apps that spend significant time in background state?
• Are there specific configuration options I'm missing to make the built-in refresh mechanism work properly in background?

Relevant log output (optional)

Error updating request status | Error: io.github.jan.supabase.postgrest.exception.PostgrestRestException: JWT expired
URL: https://XXXX.supabase.co/rest/v1/device_health_commands?id=eq.XXXX-XXXX&select=%2A
Headers: [Authorization=[Bearer XXXXXXXXXXXX], Prefer=[return=representation], Content-Profile=[public], apikey=[XXXXXXXXXXXX], X-Client-Info=[supabase-kt/3.1.4], Accept=[application/json], Accept-Charset=[UTF-8]]
Http Method: PATCH

[jan-tennert]

Can you enable debug logs in the SupabaseClientBuilder and check for any Auth logs while its in background? Or when that exception happens

[Yahouedeou]

Supabase-Auth

• Here are all logs related to the Supabase-Auth .
• Wether I put the app in the background or not, I don't have anything else printed in the logs from Supabase-Auth.

2025-04-19 14:05:44.193  5794-5794  Supabase-Auth           com.sapiensgo.android                D  Initializing Auth plugin...
2025-04-19 14:05:44.193  5794-5794  Supabase-Auth           com.sapiensgo.android                D  Initialized Auth plugin
2025-04-19 14:05:44.194  5794-5829  Supabase-Auth           com.sapiensgo.android                I  Loading session from storage...
2025-04-19 14:05:44.224  5794-5832  Supabase-Auth           com.sapiensgo.android                D  Importing session UserSession(accessToken=XXXXXXXXX, refreshToken=XXXXXXXXX, providerRefreshToken=null, providerToken=null, expiresIn=604800, tokenType=bearer, user=UserInfo(appMetadata={"provider":"email","providers":["email"]}, aud=authenticated, confirmationSentAt=2024-12-13T08:18:52.259882Z, confirmedAt=2024-12-13T08:19:05.729970Z, createdAt=2024-12-13T08:18:52.232731Z, email=XXXXXXXXX, emailConfirmedAt=2024-12-13T08:19:05.729970Z, factors=[], id= XXXXXXXXX, identities=[Identity(id= XXXXXXXXX, identityData={"email":"XXXXXXXXX","email_verified":false,"phone_verified":false,"sub":"XXXXXXXXX"}, identityId=cdaa5549-a095-4133-9984-953f28d4568b, lastSignInAt=2024-12-13T08:18:52.251735Z, updatedAt=2024-12-13T08:18:52.251795Z, createdAt=2024-12-13T08:18:52.251795Z, provider=email, userId=XXXXXXXXX)], lastSignInAt=2025-04-17T09:38:53.203616321Z, phone=, role=authenticated, updatedAt=2025-04-17T09:38:53.206398Z, userMetadata={"email":"XXXXXXXXX","email_verified":false,"phone_verified":false,"sub":"XXXXXXXXX"}, phoneChangeSentAt=null, newPhone=null, emailChangeSentAt=null, newEmail=null, invitedAt=null, recoverySentAt=2025-04-17T09:38:43.439217Z, phoneConfirmedAt=null, actionLink=null), type=, expiresAt=2025-04-24T09:38:52.209139Z) from Storage, auto refresh is set to true.
2025-04-19 14:05:44.231  5794-5832  Supabase-Auth           com.sapiensgo.android                D  Session saved to storage (auto refresh enabled)
2025-04-19 14:05:44.231  5794-5832  Supabase-Auth           com.sapiensgo.android                D  Session imported successfully. Starting auto refresh...
2025-04-19 14:05:44.232  5794-5832  Supabase-Auth           com.sapiensgo.android                D  Auto refresh started.
2025-04-19 14:05:44.232  5794-5829  Supabase-Auth           com.sapiensgo.android                D  Refreshing session in 3d 18h 57m 7.976252s.
2025-04-19 14:05:44.233  5794-5832  Supabase-Auth           com.sapiensgo.android                I  Successfully loaded session from storage!

JWT Event Logs

• Here are some breadcrumb logs from Sentry when we have an event of JWT expired

Timber
error
05:49:47.059 PM
Error getting phone number for SIM slot: 2 | Error: io.github.jan.supabase.postgrest.exception.PostgrestRestException: JWT expired
URL: https://XXXXXXXXX.supabase.co/rest/v1/phone_numbers?device_id=eq.XXXXXXXXX&sim_slot=eq.2&is_active=eq.true&select=%2A
Headers: [Authorization=[Bearer XXXXXXXXX], Content-Type=[application/json], Prefer=[], Accept-Profile=[public], apikey=[XXXXXXXXX], X-Client-Info=[supabase-kt/3.1.4], Accept=[application/json], Accept-Charset=[UTF-8]]
Http Method: GET

---------------------
---------------------
HTTP
info
05:49:45.606 PM
GET: https://XXXXXXXXX.supabase.co/rest/v1/phone_numbers [401]

{
host: wpvjenmnmvrueqieadzs.supabase.co,
http.end_timestamp: 1744998586790,
http.query: device_id=eq.XXXXXXXXX&sim_slot=eq.2&is_active=eq.true&select=%2A,
http.start_timestamp: 1744998585606,
path: /rest/v1/phone_numbers,
protocol: HTTP_2,
response_content_length: 88
}
---------------------
---------------------

SMSReceiver
debug
05:49:45.491 PM
Incoming SMS received on SIM slot: 2 | Subscription ID: 3
---------------------
---------------------
SMSReceiver
info
05:49:45.406 PM
Incoming SMS received | Starting processing
---------------------
---------------------
Device Event
info
05:49:40.234 PM

{
action: SCREEN_OFF,

extras: {
reason: 2,
why: 3
}
}
---------------------
---------------------
Device Event
info
05:49:39.754 PM

{
action: DREAMING_STARTED
}
---------------------
---------------------
Device Event
info
05:49:13.092 PM

{
action: SCREEN_ON,

extras: {
why: 2
}
}
---------------------
---------------------
Network Event
info
05:49:12.543 PM

{
action: NETWORK_CAPABILITIES_CHANGED,
download_bandwidth: 687,
network_type: wifi,
signal_strength: -54,
upload_bandwidth: 47025,
vpn_active: false
}
---------------------
---------------------
Device Event
info
05:49:12.478 PM

{
action: DREAMING_STOPPED
}
---------------------
---------------------

[sproctor]

I had this happen to me today too. Unfortunately, I wasn't logging the session status.

Error message:

Received message without event: RealtimeMessage(topic=realtime:db-changes, event=system, payload={"message":"Token has expired 0 seconds ago","status":"error","extension":"system","channel":"db-changes"}, ref=null)

The app was in the foreground for 7 minutes when this happened. Otherwise, I don't see anything relevant in my logs.

I'm still working out issues with subscriptions, so I can't say if this is a regression.

[Yahouedeou]

Could this bug be related to the previously fixed issue in v2.4.3 – Major bug fix? Specifically the one described as:

“Fix a major bug causing sessions to be refreshed later than they should be”

[jan-tennert]

No. The session expires sometime in the background and the problem is hard to pin point without logs around the time of expiration. Looking into it.

[jan-tennert]

@Yahouedeou Do you have a reproducer? Or how is your app run in the background?

[Yahouedeou]

@jan-tennert

Reproducer

• I don't have a simple reproducer for this issue. Our app uses standard Android background services with WakeLock to keep running when the app isn't in the foreground. We are not using an external library for background processes. I could share with you the GitRepo if needed.

More context around the JWT issue

• At the beginning we used the default JWT Access token expiry time settings and had some issues, so recently increased the JWT Access token expiry time to 604800s but still we are experiencing issues with background sessions not refreshing.

• Yesterday I did some tests, and by setting a very short JWT Access token expiry (120s), the session refresh works perfectly when the app is in the background. We can see the refresh operations happening in our logs.

• This makes me wonder if there's something about how Supabase handles longer lived tokens, or if we need to implement something specific to better handles tasks in the background.

• Our application is running 99% of the time in background mode with our users. The app has to be active/reacheable in order to receive FCM messages from our Backend.

[sproctor]

What happens when the refresh fails? It looks like there's no retry, but I'm not confident on that. A lot of devices shut down the wifi after a period of inactivity. If that happens and auth tries to refresh the token, what happens?

[jan-tennert]

It will retry on every exception except on rest exceptions (so on network fails and on internal server issues)

supabase-kt/Auth/src/commonMain/kotlin/io/github/jan/supabase/auth/AuthImpl.kt

Lines 460 to 476 in 4fd0c66

	} catch (e: RestException) {
	if (e.statusCode in 500..599) {
	Auth.logger.e(e) { "Couldn't refresh session due to an internal server error. Retrying in ${config.retryDelay} (Status code ${e.statusCode})..." }
	_sessionStatus.value = SessionStatus.RefreshFailure(RefreshFailureCause.InternalServerError(e))
	delay(config.retryDelay)
	retry()
	} else {
	Auth.logger.e(e) { "Couldn't refresh session. The refresh token may have been revoked. Clearing session (Status code ${e.statusCode})... " }
	clearSession()
	}
	} catch (e: Exception) {
	coroutineContext.ensureActive()
	Auth.logger.e(e) { "Couldn't reach Supabase. Either the address doesn't exist or the network might not be on. Retrying in ${config.retryDelay}..." }
	_sessionStatus.value = SessionStatus.RefreshFailure(RefreshFailureCause.NetworkError(e))
	delay(config.retryDelay)
	retry()
	}

[Yahouedeou]

• From all the bugs we had, I never saw a retry.
• To give you an example, we just had a bug 5min ago on a device from a user, on the homepage of the application we are fetching data, every time the page loads. The data showed was empty, doesn't matter how much we reloaded the page. We had to completely close the app and launch it again to get the session refreshed.
• And here is a sentry logs regarding another case when calling a edge function, but with the same sessions with the JWT expired.

[jan-tennert]

From all the bugs we had, I never saw a retry.

Well a retry is not necessarily common, if there is never a server issue or the internet is always on there won't be a retry ever.

To give you an example, we just had a bug 5min ago on a device from a user, on the homepage of the application we are fetching data, every time the page loads. The data showed was empty, doesn't matter how much we reloaded the page. We had to completely close the app and launch it again to get the session refreshed.

Well logs on that would be helpful

And here is a sentry logs regarding another case when calling a edge function, but with the same sessions with the JWT expired.

But the logs show a different error: invalid jwt?

In any case what we can do is add more checks to the session in generel. For example:

• Check if the session is expired when it's accessed and if it is, then log some data like if the session job is still running etc, then force a refresh before making a request

[jan-tennert]

@sproctor This should also prevent your issue for now and we gain more information about why the auto refresh might be stopped