docs(dart): require onError handler in onAuthStateChange examples

[grdsdev]

Summary

• Adds a warning note to onAuthStateChange() that an onError handler is required
• Updates all three Dart code examples (spotlight, specific-event, unsubscribe) to include onError

Background

Network errors (e.g. a token refresh attempted while the device is offline) are emitted as stream errors on onAuthStateChange. If no onError handler is provided, Dart rethrows them as unhandled zone exceptions, crashing the app.

This is tracked in supabase/supabase-flutter#1281. The SDK itself already handles this internally (supabase_auth.dart has its own onError), but user-facing code that calls .listen() without onError is still vulnerable.

The companion SDK fix (example app + doc comment in gotrue_client.dart) is in a separate PR in supabase/supabase-flutter.

Test plan

• Review the rendered diff in the Dart reference docs (/docs/reference/dart/auth-onauthstatechange)
• Confirm all three code examples now show onError
• Confirm the new note is visible in the Notes section

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified auth-state change docs to require explicit error handling in listeners and updated all examples to show an error callback to avoid unhandled exceptions.
  • Updated the documented list of auth event names to the new set (including initialSession and mfaChallengeVerified) and adjusted examples accordingly.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment, Open in v0	Apr 17, 2026 5:58pm

7 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
studio	Ignored		Apr 17, 2026 5:58pm
design-system	Skipped		Apr 17, 2026 5:58pm
learn	Skipped		Apr 17, 2026 5:58pm
studio-self-hosted	Skipped		Apr 17, 2026 5:58pm
studio-staging	Skipped		Apr 17, 2026 5:58pm
ui-library	Skipped		Apr 17, 2026 5:58pm
zone-www-dot-com	Skipped		Apr 17, 2026 5:58pm

[supabase]

This pull request has been ignored for the connected project xguihxuzqibwxjnimxev because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 715e1ca8-47d8-4883-b2a7-c787dbab8528

📥 Commits

Reviewing files that changed from the base of the PR and between 0bb1887 and aaaaaaf.

📒 Files selected for processing (1)

• apps/docs/spec/supabase_dart_v2.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• apps/docs/spec/supabase_dart_v2.yml

---

📝 Walkthrough

Walkthrough

Updated the Supabase Dart v2 documentation to require providing an onError handler when using onAuthStateChange(); code examples (including unsubscribe) were changed to use the listen overload that accepts both a data callback and an onError callback. Auth event names list was revised.

Changes

Cohort / File(s)	Summary
Authentication Documentation apps/docs/spec/supabase_dart_v2.yml	Require onError handler for onAuthStateChange(); replace documented auth event names with the new set (initialSession, signedIn, signedOut, passwordRecovery, tokenRefreshed, userUpdated, userDeleted, mfaChallengeVerified); update all supabase.auth.onAuthStateChange.listen(...) examples (including unsubscribe) to show the onError: (error, stackTrace) { ... } overload.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through lines of docs today,

"Add onError!" I cried, in a cheery way.
Streams now catch what might have fled,
No more surprises jumping out of bed.
Happy tails and safe event play! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides context and rationale, but does not follow the required template structure with sections like 'What kind of change', 'Current behavior', 'New behavior', etc.	Restructure the description to follow the template: explicitly state 'What kind of change' (docs update), link relevant issues, describe current vs new behavior, and include any additional context.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding required onError handler documentation to onAuthStateChange examples in Dart.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/dart-on-auth-state-change-error-handler

---

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 and usage tips.}

[github-actions]

Braintrust eval report

Assistant (master-1776683002)

Score	Average	Improvements	Regressions
Completeness	98% (-2pp)	-	1 🔴
Conciseness	24.5% (-3pp)	3 🟢	5 🔴
Docs Faithfulness	71.2% (-10pp)	2 🟢	2 🔴
Goal Completion	93.1% (+1pp)	3 🟢	2 🔴
Tool Usage	73.8% (-2pp)	-	1 🔴
Knowledge Usage	100% (+0pp)	-	-
Correctness	100% (+0pp)	-	-
SQL Identifier Quoting	100% (+0pp)	-	-
SQL Validity	100% (+0pp)	-	-
URL Validity	100% (+33pp)	-	-
Time_to_first_token	0.01tok (+0.01tok)	1 🟢	16 🔴
Llm_calls	12.18 (+0.04)	8 🟢	7 🔴
Tool_calls	3.71 (+0.16)	9 🟢	5 🔴
Errors	0 (+0)	-	-
Llm_errors	0 (+0)	-	-
Tool_errors	0 (+0)	-	-
Prompt_tokens	26320.75tok (-336.06tok)	5 🟢	12 🔴
Prompt_cached_tokens	0tok (+0tok)	-	-
Prompt_cache_creation_tokens	0tok (+0tok)	-	-
Completion_tokens	627.96tok (+35.22tok)	6 🟢	11 🔴
Completion_reasoning_tokens	0tok (+0tok)	-	-
Completion_accepted_prediction_tokens	0tok (+0tok)	-	-
Completion_rejected_prediction_tokens	0tok (+0tok)	-	-
Completion_audio_tokens	0tok (+0tok)	-	-
Total_tokens	26948.71tok (-300.84tok)	5 🟢	12 🔴
Estimated_cost	0.01$ (0$)	5 🟢	10 🔴
Duration	26.26s (+8.26s)	7 🟢	10 🔴
Llm_duration	71.78s (+23.25s)	7 🟢	10 🔴