Fatal exception when offline

[BoondoggleLabs]

Supabase flutter throws:
[ERROR:flutter/runtime/dart_vm_initializer.cc(40)] Unhandled Exception: AuthRetryableFetchException(message: ClientException with SocketException: Failed host lookup when the device can't reach the internet.

Surely we should be able to handle temporary offline states without the app crashing?

Full Log:

AuthRetryableFetchException (AuthRetryableFetchException(message: ClientException with SocketException: Failed host lookup: 'redacted.supabase.co' (OS Error: No address associated with hostname, errno = 7), uri=https://redacted.supabase.co/auth/v1/token?grant_type=refresh_token, statusCode: null)) [sentry.platformError] #0 GotrueFetch._handleRequest (package:gotrue/src/fetch.dart:190:7) fetch.dart:190 <asynchronous suspension> #1 GotrueFetch.request (package:gotrue/src/fetch.dart:141:12) fetch.dart:141 <asynchronous suspension> #2 GoTrueClient._refreshAccessToken.<anonymous closure> (package:gotrue/src/gotrue_client.dart:1112:26) gotrue_client.dart:1112 <asynchronous suspension> #3 RetryOptions.retry (package:retry/retry.dart:131:16) retry.dart:131 <asynchronous suspension> #4 GoTrueClient._refreshAccessToken (package:gotrue/src/gotrue_client.dart:1103:12) gotrue_client.dart:1103 <asynchronous suspension> #5 GoTrueClient._callRefreshToken (package:gotrue/src/gotrue_client.dart:1273:20) gotrue_client.dart:1273 <asynchronous suspension> #6 GoTrueClient.recoverSession (package:gotrue/src/gotrue_client.dart:1022:18) gotrue_client.dart:1022 <asynchronous suspension> #7 SupabaseAuth.recoverSession (package:supabase_flutter/src/supabase_auth.dart:94:11) supabase_auth.dart:94 <asynchronous suspension> #8 CancelableCompleter.complete.<anonymous closure> (package:async/src/cancelable_operation.dart:433:16) cancelable_operation.dart:433 <asynchronous suspension>

[grdsdev]

Thanks for reporting this issue, @BoondoggleLabs!

This does appear to be a bug. The SDK should handle offline scenarios gracefully instead of crashing with an unhandled exception. When recoverSession() attempts to refresh the access token while offline, the network error (SocketException: Failed host lookup) is not being caught and handled properly, causing the app to crash.

We're tracking this and will investigate further. The issue appears to stem from missing error handling in the async chain, particularly in:

• SupabaseAuth.recoverSession()
• GoTrueClient.recoverSession()
• GoTrueClient._refreshAccessToken()

The expected behavior would be for the SDK to catch network errors gracefully, return null or a failure result instead of throwing, and allow the app to continue with cached session data when available.

We'll update this issue as we make progress on the fix. If you have any additional context or can share a minimal reproducible example, that would be helpful!

[BoondoggleLabs]

The stack trace shows the error originates from GoTrueClient.recoverSession() → _callRefreshToken() → _refreshAccessToken(), and bubbles up through CancelableOperation.fromFuture().

The issue is in GoTrueClient.notifyException() (gotrue_client.dart:1331-1337):

Object notifyException(Object exception, [StackTrace? stackTrace]) {
  _log.warning('Notifying exception', exception, stackTrace);
  _onAuthStateChangeController.addError(  // <-- Problem here
    exception,
    stackTrace ?? StackTrace.current,
  );
  return exception;
}

When a network error occurs (e.g., device offline), notifyException() pushes the error to _onAuthStateChangeController via addError(). This causes the error to propagate as an unhandled async exception, even though:

1. SupabaseAuth.recoverSession() has a catch block that should swallow it
2. The listener in supabase_auth.dart:48 has an empty onError handler

The error escapes because BehaviorSubject.addError() propagates to all subscribers, and any subscriber without an explicit onError handler will cause an unhandled exception.

Expected Behavior

AuthRetryableFetchException should be handled gracefully when offline. The SDK should:

• Log the error
• Continue retrying in the background
• Not propagate retryable network errors to the auth state stream

Workaround

I found I can get around this in my app for now:

Add onError handlers to all onAuthStateChange.listen() calls:

Supabase.instance.client.auth.onAuthStateChange.listen(
  (data) { /* handle auth state */ },
  onError: (_, __) {}, // Swallow network errors
);

[Vinzent03]

Your workaround is exactly what I wanted to comment. You are currently expected to add an onError handler. I wouldn't consider this a bug. We should probably add this to the documentation of the stream, but exceptions are added to the stream, and it's the natural behavior of a Dart stream to consider them unhandled and throw them in the next zone if no error handler is set.

Just logging the network error would not allow the application to handle such cases. You might want to show in the UI that it's currently trying to reconnect. So by adding the exception to the stream we offer a way to react to it.

[BoondoggleLabs]

Fair enough @Vinzent03 in which case this should at least be made clearer in the documentation and the example code should have an onError added (currently the example code will crash when offline as described)