How to fix PERMISSION_DENIED: The caller does not have the required role in Firebase

For client-side Firestore access, verify that your user is properly authenticated before attempting database operations:

import { getAuth } from "firebase/auth";
import { getFirestore, doc, getDoc } from "firebase/firestore";

const auth = getAuth();
const currentUser = auth.currentUser;

if (currentUser) {
  console.log("User authenticated:", currentUser.uid);
  const db = getFirestore();
  const docRef = doc(db, "users", currentUser.uid);
  const docSnap = await getDoc(docRef);
} else {
  console.log("User not authenticated");
  // Sign in user first
}

If the user is not authenticated, sign them in using Firebase Authentication before accessing Firestore.

Access the Firestore Security Rules in the Firebase Console and ensure they allow the operations your users need. For authenticated users with basic read/write access:

service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

For user-specific access, use more granular rules:

service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth.uid == userId;
    }
    match /public/{document=**} {
      allow read: if true;
    }
  }
}

After updating rules, click "Publish" and wait for them to deploy (usually 1-2 minutes).

For Cloud Functions or backend services using the Admin SDK, grant the required IAM roles to the service account in Google Cloud Console:

1. Go to Google Cloud Console > IAM & Admin > IAM
2. Find the service account (usually named "App Engine default service account" with format: [email protected])
3. Click the edit icon and add these roles:
- Cloud Datastore User (roles/datastore.user) - minimum required
- Firebase Admin (roles/firebase.admin) - broader access

Alternatively, use the gcloud CLI:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:[email protected] \
  --role=roles/datastore.user

# Or for broader access:
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:[email protected] \
  --role=roles/firebase.admin

After granting roles, it takes up to 5 minutes for the permissions to take effect due to IAM caching.

Ensure the necessary APIs are enabled in your Google Cloud project:

1. Go to Google Cloud Console > APIs & Services > Library
2. Search for and enable:
- Cloud Firestore API
- Cloud Functions API (if using functions)
- Service Usage API

Using the gcloud CLI:

gcloud services enable firestore.googleapis.com
gcloud services enable cloudfunctions.googleapis.com
gcloud services enable serviceusage.googleapis.com

Missing enabled APIs will cause permission errors even with correct IAM roles.

Before deploying security rule changes to production, test them in the Firebase Console:

1. In Firebase Console, go to Firestore Database > Rules
2. Click the Rules Playground button (or tab)
3. Enter test values:
- Authentication: Mock the auth object (set uid, email, or custom claims)
- Request path: The document path being accessed (e.g., /users/user123)
- Request method: Read, Write, or Delete
4. Click Run to see if the rule allows or denies the request
5. Iterate on rules until tests pass
6. Click Publish to deploy

This prevents deploying broken rules to production.

If using a custom service account (not App Engine default), verify credentials are correct:

1. Go to Google Cloud Console > Service Accounts
2. Select your service account and click Keys
3. If the key is old or expired, create a new one:
- Click Add Key > Create new key > JSON
- Download and store securely
4. In your backend code, initialize the Admin SDK:

import admin from 'firebase-admin';

const serviceAccount = require('./path/to/serviceAccountKey.json');

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
  databaseURL: 'https://YOUR_PROJECT.firebaseio.com',
});

const db = admin.firestore();
// Now you can access Firestore without permission issues

The Admin SDK bypasses security rules entirely, so if you still get permission errors with Admin SDK, it indicates an IAM role problem, not a security rules problem.