Skip to content

fix: make DataStreamError a LiveKitException - #1294

Merged
hiroshihorie merged 1 commit into
mainfrom
hiroshi/data-stream-error-livekit-exception
Nov 17, 2026
Merged

hiroshihorie merged 1 commit into
mainfrom
hiroshi/data-stream-error-livekit-exception

Conversation

@hiroshihorie

Copy link
Copy Markdown
Member

Problem

DataStreamError was declared implements Exception, so it was not a LiveKitException, the base type the SDK documents for what it throws. An app that catches stream writes with on LiveKitException missed it.

Since data streams v2 (#1166), native writes go through the Rust core. A write still in the core when the room is disposed fails with DataStreamError(AbnormalEnd), which comes from the core's InternalDataStreamException via the catch-all in toLKError. The e2e scenario "Dispose during backpressured stream writes" expects every such write to fail with a LiveKitException, and found this.

Change

  • DataStreamError now implements LiveKitException (the base class's constructor is private, so it can't be extended). message gets @override; toString() is unchanged.
  • The comment on DataStreamErrorReason.AbnormalEnd said "closed abnormally by remote participant". It now lists everything that maps to this reason: the sender leaving mid-stream, the local room disconnecting or being disposed, an I/O failure, and the FFI catch-all. The enum itself is unchanged.

What I checked

  • Catch sites in lib/: none behaves differently. The only supertype check is Checker.messageFor (error is LiveKitException), and connection checks don't use data streams. Every other check names a specific type that DataStreamError doesn't match: ConnectException, CertificatePinningException, NegotiationError, UnexpectedConnectionState, MediaConnectException, RpcError, PlatformException, or ffi.DataStreamException. The data stream and RPC code catches errors without checking the type, then logs them or wraps them in RpcError from e.toString(). That string comes from toString(), which is unchanged.
  • History: Data streams v2 #1166 (f38055a) is not in any release. v2.13.2 was tagged from release/2.13.2 and contains only a flutter_webrtc bump. Before Data streams v2 #1166 on main, a write on a closed engine failed with UnexpectedConnectionState (Fix waiting for the data channel send buffer to drain #1267/Announce engine closure on disposal and terminal reconnect failure #1268, also unreleased). In 2.13.x, by reading the code: a write waiting on the buffer polled forever, because dispose didn't announce engine closure yet. A write already sending hit the closed channel and failed with a PlatformException; the e2e case's note on Send reliable data after a full reconnect instead of dropping it #1277 agrees. So this is not a regression from a release. In 2.13.x DataStreamError was never a LiveKitException for any reason, readers included, so this is new behaviour for users.
  • Web: web still runs the Dart writer, which waits in engine.waitForBufferStatusLow and fails with UnexpectedConnectionState. That is already a LiveKitException. After this change both platforms fail the write with a LiveKitException, but the concrete types still differ: web gives UnexpectedConnectionState, native gives DataStreamError(AbnormalEnd). On native, a write issued after the engine has closed still gets UnexpectedConnectionState from _ensureOpen, as before.
  • API compatibility: dart-apitool diff against origin/main (298cc62) reports "No breaking changes!", with one minor change: Super Type "LiveKitException" added (CI04). The tool rates an added supertype as a minor change. The changeset is patch for now; minor vs patch is the owner's call.
  • Pending changesets: this changeset and the pending .changes/buffer-wait-typed-error read slightly inconsistently on native. That one says writes on a closed engine fail with UnexpectedConnectionState, which holds for a write issued after the engine closed. A write already in the core when the room is disposed gets DataStreamError (now a LiveKitException). Whoever writes the release notes should reconcile the two lines. I left the other changeset unchanged.

Tests

Added writes cut off by disposing the room fail with a LiveKitException to test/core/data_stream_v2_test.dart. It runs the real Rust core through the mock container: it starts 50 unawaited 30 KB writes on a byte stream, disposes the room, and checks that at least one write failed and that every failure is a LiveKitException. Without the change all 50 fail with DataStreamError, which is not a LiveKitException, and the test fails. With it, the test passed 5 times out of 5.

Holding a write in a full send buffer doesn't reproduce this on native: the core's outgoing queue is unbounded, so writes return as soon as the core has queued them.

flutter analyze, flutter test, dart format, import_sorter, and check_version all pass.

🤖 Generated with Claude Code

A data stream write cut off by disposing the room fails on native with a
DataStreamError, which only implemented Exception, so apps catching
LiveKitException missed it. DataStreamError now implements
LiveKitException; its toString() is unchanged.

Also correct the AbnormalEnd comment: the reason covers local disconnect
or dispose and I/O failures, not only a remote participant leaving.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@hiroshihorie
hiroshihorie marked this pull request as ready for review November 17, 2026 07:16

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@hiroshihorie
hiroshihorie merged commit f1c7450 into main Nov 17, 2026
16 checks passed
@hiroshihorie
hiroshihorie deleted the hiroshi/data-stream-error-livekit-exception branch November 17, 2026 07:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant