FlutterRealtimeCloud

🐛 Realtime Flutter SDK Crash – RealtimeMessage.fromMap TypeError

Mar 1, 2026, 13:03

View on Discord

Votes

Replies

Participants

Unknown

Messages

!Original post

Flutter Developer

Mar 1, 2026, 12:33

Summary
When using Appwrite Cloud with the Flutter SDK (latest appwrite release: 21.4.0), Realtime crashes with:

Plain text

#0      new RealtimeMessage.fromMap (package:appwrite/src/realtime_message.dart:57:47)```
The crash occurs as soon as a real Realtime event (`.create`, `.update`, `.delete`) is received. Heartbeat messages work fine.

This happens before the event reaches the user’s sub.stream.listen(...) callback.


**Environment**
- Appwrite Cloud
- Endpoint: https://cloud.appwrite.io/v1
- Flutter SDK: appwrite: 21.4.0
- Platform: Android (Flutter)


**Root Cause**
Inside the Flutter SDK, RealtimeMessage.fromMap assumes that:

events: List
channels: List

However, under certain conditions, the Realtime WebSocket payload delivers `events` and/or `channels` as a Map instead of a `List`.

Because the SDK strictly casts:

(map['events'] as List)

it throws:

type '_Map<String, dynamic>' is not a subtype of type 'Iterable'

This indicates the parser is not tolerant to slight payload structure variations.


**Reproduction**
Minimal example:

final sub = realtime.subscribe([
'databases.{dbId}.collections.{collectionId}.documents'
]);

sub.stream.listen((event) {
print(event);
});

As soon as a document `.create` or `.update` event is triggered,
the SDK crashes in `RealtimeMessage.fromMap`.

Summary

Developers encountered crashes in the Realtime Flutter SDK due to a TypeError in RealtimeMessage.fromMap. The proposed fix involves making the parsing function tolerant to both List and Map inputs. By applying the provided patch, Realtime functions reliably without crashes, solving the issue before user code handles errors. This crash renders Realtime unusable in production Flutter apps but can be quickly fixed with the small, backward-compatible change proposed.

Flutter Developer

Mar 1, 2026, 12:33

Proposed Fix (Robust Parsing)
Making RealtimeMessage.fromMap tolerant to both List and Map resolves the issue completely.

Example patch:

static List<String> _coerceStringList(dynamic v) {
  if (v == null) return const [];
  if (v is List) return v.map((e) => e.toString()).toList();
  if (v is Map) return v.values.map((e) => e.toString()).toList();
  return [v.toString()];
}

factory RealtimeMessage.fromMap(Map<String, dynamic> map) {
  final dynamic data = map['data'];
  final Map<String, dynamic> m =
      data is Map<String, dynamic> ? data : map;

  return RealtimeMessage(
    events: _coerceStringList(m['events']),
    payload: Map<String, dynamic>.from(m['payload'] ?? const {}),
    channels: _coerceStringList(m['channels']),
    timestamp: (m['timestamp'] ?? '').toString(),
  );
}

After applying this change locally, Realtime works reliably without crashes.

Why This Matters

The crash occurs before user code can handle errors.
It makes Realtime unusable in production Flutter apps.
The fix is small and backward-compatible.
Making parsing tolerant prevents similar crashes in the future if payload shape slightly changes.

🐛 Realtime Flutter SDK Crash – RealtimeMessage.fromMap TypeError

Need support?_