Unhandled AuthRetryableFetchException from SupabaseAuth.recoverSession() when backend becomes unavailable at runtime

[daniel1414]

Describe the bug
When the app starts with a valid cached session and the backend becomes unavailable while the app is still running, supabase_flutter appears to surface an unhandled exception from its internal session recovery / refresh path.

My app can tolerate backend unavailability at the application layer, but supabase_flutter still emits an unhandled exception to Flutter’s global error handler.

To Reproduce
Steps to reproduce the behavior:

1. Run local Supabase.
2. Launch the app and sign in so a session is cached.
3. Keep the app running.
4. Stop the local Supabase container.
5. Wait for auth recovery / refresh.
6. Observe unhandled AuthRetryableFetchException in Flutter logs.

Observed behavior

• app starts normally with a cached session
• local Supabase container is stopped while app is running
• after auth recovery / refresh kicks in, Flutter receives repeated unhandled exceptions:

1. AuthRetryableFetchException
2. stack includes SupabaseAuth.recoverSession
3. stack also includes CancelableCompleter.complete.

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots

• backend unavailability should be reported through auth state / error streams / callbacks
• it should not escape as an unhandled exception during a normal connectivity outage

Version (please complete the following information):
On Linux
supabase_flutter 2.12.4
│ ├── supabase 2.10.6
│ │ ├── functions_client 2.5.0
│ │ ├── gotrue 2.20.0
│ │ ├── postgrest 2.7.0
│ │ ├── realtime_client 2.7.3
│ │ ├── storage_client 2.5.2

Minimal example

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  FlutterError.onError = (details) {
    debugPrint('FLUTTER ERROR: ${details.exception}');
    debugPrintStack(stackTrace: details.stack);
  };

  await Supabase.initialize(
    url: 'http://127.0.0.1:54321',
    anonKey: 'YOUR_ANON_KEY',
    authOptions: const FlutterAuthClientOptions(
      detectSessionInUri: false,
    ),
  );

  final auth = Supabase.instance.client.auth;

  auth.onAuthStateChange.listen(
    (state) {
      debugPrint('AUTH EVENT: ${state.event}');
    },
    onError: (error, stackTrace) {
      debugPrint('AUTH STREAM ERROR: $error');
      debugPrintStack(stackTrace: stackTrace);
    },
  );

  runApp(const MaterialApp(home: Scaffold(body: Center(child: Text('Run app, then stop Supabase')))));
}