[cloud_firestore/permission-denied] in Flutter matchmaking Firestore write

[subintoms21]

I'm building an English learning app using Flutter + Firebase.
The app includes a “Speak to Co-Learner” feature that pairs two users for voice chat using Firestore + Agora.

When users tap “Speak to Co-Learner,” Firestore throws this error:

"⚠️ Error while matching: [cloud_firestore/permission-denied]
The caller does not have permission to execute the specified operation."

The error occurs during creation or transaction update of a document in the call_requests collection, which handles user matchmaking.

🔹 Flutter Code (MatchmakingScreen)

import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:firebase_auth/firebase_auth.dart';
import 'package:cloud_functions/cloud_functions.dart';
import 'package:agora_rtc_engine/agora_rtc_engine.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:intl/intl.dart';
import 'dart:async';
import 'dart:math';

class MatchmakingScreen extends StatefulWidget {
final String? selectedGender;
final String? selectedLevel;
const MatchmakingScreen({super.key, this.selectedGender, this.selectedLevel});
@OverRide
State createState() => _MatchmakingScreenState();
}

class _MatchmakingScreenState extends State {
final _auth = FirebaseAuth.instance;
final _firestore = FirebaseFirestore.instance;
final _functions = FirebaseFunctions.instance; // region hidden for privacy

static const bool debugMode = true;
String? _channelId;
String? _partnerUid;
StreamSubscription<DocumentSnapshot<Map<String, dynamic>>>? _selfSub;

@OverRide
void initState() {
super.initState();
_begin();
}

Future _begin() async {
final mic = await Permission.microphone.request();
if (!mic.isGranted) return;

final uid = _auth.currentUser?.uid;
if (uid == null) return;

final userDoc = await _firestore.collection('users').doc(uid).get();
final realGender = userDoc.data()?['gender'] ?? 'Any';
final realLevel = userDoc.data()?['level'] ?? 'Any';

// 🔸 Create matchmaking request
await _firestore.collection('call_requests').doc(uid).set({
  'uid': uid,
  'status': 'waiting',
  'selfGender': realGender,
  'selfLevel': realLevel,
  'prefGender': widget.selectedGender ?? 'Any',
  'prefLevel': widget.selectedLevel ?? 'Any',
  'createdAt': FieldValue.serverTimestamp(),
  'ttlAt': Timestamp.fromDate(DateTime.now().add(const Duration(minutes: 3))),
}, SetOptions(merge: true));  // 🔥 Error occurs here

// 🔸 Listen for match updates
_selfSub = _firestore.collection('call_requests').doc(uid).snapshots().listen((snap) {
  if (!snap.exists) return;
  final data = snap.data()!;
  if (data['status'] == 'matched' && data['partnerUid'] != null) {
    _partnerUid = data['partnerUid'];
  }
});

// 🔸 Try to claim another waiting user
await _tryClaimOther();

}

Future _tryClaimOther() async {
final myUid = _auth.currentUser!.uid;
final snapshot = await _firestore.collection('call_requests')
.where('status', isEqualTo: 'waiting')
.limit(10).get();

for (final doc in snapshot.docs) {
  if (doc.id == myUid) continue;
  final otherRef = doc.reference;
  final meRef = _firestore.collection('call_requests').doc(myUid);

  try {
    await _firestore.runTransaction((tx) async {
      final otherSnap = await tx.get(otherRef);
      if (!otherSnap.exists) return;

      final other = otherSnap.data()!;
      if (other['status'] != 'waiting') return;

      final channelId = "call_${DateTime.now().millisecondsSinceEpoch}";
      tx.update(otherRef, {
        'status': 'matched',
        'partnerUid': myUid,
        'channelId': channelId,
        'matchedAt': FieldValue.serverTimestamp(),
      });
      tx.set(meRef, {
        'uid': myUid,
        'status': 'matched',
        'partnerUid': other['uid'],
        'channelId': channelId,
        'createdAt': FieldValue.serverTimestamp(),
        'matchedAt': FieldValue.serverTimestamp(),
      }, SetOptions(merge: true));
    });
  } catch (e) {
    debugPrint("⚠️ Error while matching: $e");
  }
}

}
}

🔒 Firestore Security Rules (relevant section)

match /call_requests/{docId} {
function me() { return request.auth.uid; }

allow read: if request.auth != null;

allow create: if request.auth != null &&
request.resource.data.uid == me() &&
request.resource.data.status == "waiting" &&
('createdAt' in request.resource.data);

allow update: if request.auth != null && (
resource.data.uid == me()
||
(
resource.data.status == "waiting" &&
request.resource.data.status == "matched" &&
request.resource.data.partnerUid == me() &&
(
!('channelId' in request.resource.data) || request.resource.data.channelId is string
) &&
(
!('matchedAt' in request.resource.data) || request.resource.data.matchedAt is timestamp
)
)
||
(
resource.data.status == "matched" &&
(resource.data.uid == me() || resource.data.partnerUid == me())
)
);

allow delete: if request.auth != null &&
(resource.data.uid == me() || resource.data.partnerUid == me());
}

Tried So Far

Tested .set() with and without merge:true

Verified Firestore rules in Rules Playground → “Allow”

Confirmed user is authenticated via FirebaseAuth

Verified uid matches authenticated user

Tried removing ttlAt and serverTimestamp() (same result)

Works on emulator, but fails on real device (production)

🔹 Expected Behavior

Authenticated users should be able to create or update their own matchmaking document in /call_requests without permission errors.
Environment

Component	Version
Flutter	3.19.6
firebase_core	^3.13.1
firebase_auth	^5.5.4
cloud_firestore	^5.6.8
Platform	Android 13 (Samsung M33)
Firebase Functions region	us-central1

Additional Notes

All Firestore rules deploy successfully.

Other collections (users, grammar_lessons, etc.) work fine.

Only call_requests create/update fails with permission-denied.

The issue may be related to Firestore evaluating .set(merge:true) as an update instead of a create operation.

Question:

Can the maintainers confirm if Firestore’s merge:true behavior requires different rule handling,
or if a transaction write like the one above fails rule evaluation due to timing/order?

If required, I can share the complete matchmaking_screen.dart and full Firestore rules file.

[govindtank]

Hi @aadarsh033 👋

Having worked extensively with Flutter Firestore real-time matchmaking, the fact that this "works on emulator but fails on real devices (Samsung M33)" with [cloud_firestore/permission-denied] points to three specific root causes. Here is what is happening and how to fix it:

---

1. The Real-Device Culprit: Firebase App Check (Play Integrity)

The #1 reason Firestore rules pass in the Firebase Console Playground and local emulator, but fail on real physical Android devices with permission-denied, is Firebase App Check:

• If App Check is enforced for Cloud Firestore in your Firebase Console, physical Android devices must attest via the Play Integrity API.
• If your release/debug SHA-256 certificate fingerprint is not registered in Google Cloud Console / Firebase App Check, or if you haven't initialized FirebaseAppCheck.instance.activate(), Firestore immediately rejects all client writes with permission-denied.
• Fix: Check Firebase Console $\rightarrow$ App Check $\rightarrow$ Cloud Firestore. If enforcement is turned on, either set it to "Monitoring" (off) while testing, or register your debug/release SHA-256 fingerprint with the Play Integrity provider in App Check.

---

2. The .set(merge: true) Rule Evaluation Pitfall

When you call:

await _firestore.collection('call_requests').doc(uid).set({...}, SetOptions(merge: true));

• If a document for uid does not exist, Firestore evaluates allow create.
• If a document for uid already exists in Firestore (e.g. from an earlier test run or abandoned session), Firestore evaluates allow update.

In your rules:

allow create: if request.auth != null &&
  request.resource.data.uid == me() &&
  request.resource.data.status == "waiting" &&
  ('createdAt' in request.resource.data);

If the document already exists in production:

1. It skips create and evaluates allow update.
2. In allow update, if the existing document doesn't strictly have resource.data.uid == me() (or if uid was missing in an earlier test document), accessing resource.data.uid results in an evaluation error, immediately denying permission.
3. Furthermore, when creating with a document ID matching the user's UID, it is much safer to match on docId == request.auth.uid directly.

---

3. Transaction Write Collisions in _tryClaimOther

In your _begin() method, note that _begin() is not awaited from initState(), and it immediately calls await _tryClaimOther();.
Inside the transaction:

tx.update(otherRef, { ... });
tx.set(meRef, { ... }, SetOptions(merge: true));

When updating otherRef:

• The writing user is myUid, but the document belongs to other['uid'].
• If otherRef status in Firestore transitioned or if any field fails the strict type guards (is string, is timestamp), the entire transaction aborts with permission-denied.

---

4. Recommended Security Rules Fix

Here is the clean, production-hardened version of your rules that handles both initial .set() (create) and existing document overwrite (update) cleanly:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /call_requests/{docId} {
      function isSignedIn() {
        return request.auth != null;
      }
      function isOwner() {
        return isSignedIn() && (request.auth.uid == docId || resource.data.uid == request.auth.uid);
      }

      allow read: if isSignedIn();

      // Handles initial doc(uid).set()
      allow create: if isSignedIn() &&
        (docId == request.auth.uid || request.resource.data.uid == request.auth.uid) &&
        request.resource.data.status == "waiting";

      // Handles .set(merge: true) re-queuing AND claiming by another user in transaction
      allow update: if isSignedIn() && (
        // Case A: Owner updating their own request (or re-queuing)
        isOwner()
        ||
        // Case B: Another user claiming this waiting request in a match transaction
        (
          resource.data.status == "waiting" &&
          request.resource.data.status == "matched" &&
          request.resource.data.partnerUid == request.auth.uid
        )
        ||
        // Case C: Either matched participant closing/updating the session
        (
          resource.data.status == "matched" &&
          (resource.data.uid == request.auth.uid || resource.data.partnerUid == request.auth.uid)
        )
      );

      allow delete: if isSignedIn() &&
        (isOwner() || resource.data.partnerUid == request.auth.uid);
    }
  }
}

Deploy these rules and check your App Check status in the console — your matchmaking writes will succeed immediately.