fix(auth)!: throw AuthSessionMissingException when a token response has no session

[spydon]

What

The auth methods that always return a Session now throw AuthSessionMissingException when the server response carries no session, instead of a plain AuthException without an errorCode. Callers can catch the case by type or by errorCode (session_missing) rather than matching on the message.

This covers every method backed by the shared helper: signInAnonymously, signInWithPassword, signInWithIdToken, signInWithWeb3, linkIdentityWithIdToken, passkey.verifyAuthentication (and with it signInWithPasskey and signInWithRestoreKey) and refreshSession.

setInitialSession and recoverSession, which already reported session_missing for a stored session missing data, now throw the same type too, so on AuthSessionMissingException catches every session_missing failure.

The exception also carries the requestId of the response, so these call sites now use requestWithResponse to hand the helper the response headers.

Breaking change

AuthSessionMissingException takes its message as a named parameter, next to the new requestId, in line with the other auth exceptions. MIGRATION.md is updated in the existing sections that described these methods throwing an AuthException and AuthSessionMissingException being raised without a request.

Refresh behavior is unchanged: the exception is still a non-retryable AuthException, so a refresh that gets no session back signs out as before.

Tests

missing_session_response_test.dart now covers every method above and asserts the type, errorCode and requestId. The refreshSession case starts signed in and checks that it signs out with SignOutReason.sessionExpired.

Fixes SDK-2260

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 27 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: supabase/supabase-flutter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0480e256-6404-454e-95aa-d7d4b8bff630

📥 Commits

Reviewing files that changed from the base of the PR and between 8bdd630 and dc884f6.

📒 Files selected for processing: 6

• MIGRATION.md
• packages/supabase_auth/lib/src/auth_client.dart
• packages/supabase_auth/lib/src/auth_passkey_api.dart
• packages/supabase_auth/lib/src/types/auth_exception.dart
• packages/supabase_auth/test/missing_session_response_test.dart
• packages/supabase_auth/test/src/types/auth_exception_test.dart

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: supabase/supabase-flutter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 441933a3-6fe4-4022-989d-0c0de168a372

📥 Commits

Reviewing files that changed from the base of the PR and between c9f89d5 and 8bdd630.

📒 Files selected for processing: 6

• MIGRATION.md
• packages/supabase_auth/lib/src/auth_client.dart
• packages/supabase_auth/lib/src/auth_passkey_api.dart
• packages/supabase_auth/lib/src/types/auth_exception.dart
• packages/supabase_auth/test/missing_session_response_test.dart
• packages/supabase_auth/test/src/types/auth_exception_test.dart

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

📝 Walkthrough

Auth session-producing requests now retain HTTP response metadata through session parsing. When a response contains no session, the client throws AuthSessionMissingException with session_missing and the response requestId. The exception accepts named message and requestId arguments. Tests and migration guidance cover the updated behavior.

Changes: Missing-session handling

Layer / File(s)	Summary
Missing-session exception contract packages/supabase_auth/lib/src/types/auth_exception.dart, packages/supabase_auth/lib/src/auth_client.dart, packages/supabase_auth/test/src/types/auth_exception_test.dart, MIGRATION.md	AuthSessionMissingException accepts named message and requestId arguments. setSession and getClaims pass missing-token messages by name. The exception test checks that a supplied request ID is retained. The migration guide describes the updated constructor and client-raised exceptions.
Response metadata and session parsing packages/supabase_auth/lib/src/auth_client.dart, packages/supabase_auth/lib/src/auth_passkey_api.dart, packages/supabase_auth/test/missing_session_response_test.dart, MIGRATION.md	Session-producing requests use requestWithResponse and pass the body and HTTP response to session parsing. When no session is returned, parsing throws AuthSessionMissingException with the response request ID. Tests check the exception type, message, error code, request ID, and absence of a session across sign-in, linking, passkey authentication, and refresh cases. The migration guide documents the affected methods.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant AuthClient
  participant AuthFetch
  participant SessionParser
  participant AuthSessionMissingException
  AuthClient->>AuthFetch: requestWithResponse
  AuthFetch-->>AuthClient: response body and HTTP response
  AuthClient->>SessionParser: parse session from body and response
  SessionParser->>AuthSessionMissingException: throw with response requestId when session is absent

Loading

Suggested reviewers: androidpoet

Merge Risk: ⚪ Minimal · up to 8bdd6

The reviewed missing-session handling is ready to merge after normal checks.

Pre-merge checks: 5

Check name	Status	Explanation
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: auth token responses without a session now throw AuthSessionMissingException.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (6 skipped: 6 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}