Firebase Admin SDK Firestore in Next.js Throws TypeError: 'payload' Must Be an Object

Below is a list of troubleshooting steps and suggestions that have helped others resolve similar issues.

---

1. Verify the Service Key Is Loaded Correctly

If the service key JSON isn’t properly loaded, it might be null or missing fields that Firebase needs. Ensure that:

• The path "@/service_key.json" is correct relative to the file that’s importing it.
• The JSON file is being bundled or copied in the server environment. In Next.js, sometimes JSON files aren’t available in production because of build optimizations. Consider using an environment variable (e.g., process.env.FIREBASE_SERVICE_ACCOUNT) or ensuring that the file is correctly included only on the server.

For extra safety, add a sanity check:

TYPESCRIPTCopied
const serviceKey = require("@/service_key.json");

if (!serviceKey || typeof serviceKey !== "object") {
  throw new Error("Service key is missing or not a valid object");
}

---

2. Sanitize the Private Key Formatting

It’s common for the Firebase service account JSON’s private key to include escaped newline characters (e.g., \\n instead of \n). This can cause errors like “length is outside of buffer bounds.” Before initializing the Firebase Admin SDK, replace the escaped newlines:

TYPESCRIPTCopied
if (serviceKey.private_key) {
  serviceKey.private_key = serviceKey.private_key.replace(/\\n/g, "\n");
}

This ensures the private key is correctly formatted when passed to cert(serviceKey).

---

3. Double Check Clerk’s Session Claims

Since you’re also using Clerk, be sure that sessionClaims (especially the email field) is properly defined. Although not directly related to the Firestore error, if sessionClaims?.email is undefined, subsequent calls might fail. Ensure your authentication returns the expected claims.

TYPESCRIPTCopied
const { sessionClaims } = await auth();
if (!sessionClaims || !sessionClaims.email) {
  throw new Error("No valid session or email found in sessionClaims");
}

---

4. Confirm the Firebase Admin SDK Initialization

Your current initialization logic appears sound. With the above adjustments, your initialization should be similar to:

TYPESCRIPTCopied
import { initializeApp, getApps, App, getApp, cert } from "firebase-admin/app";
import { getFirestore } from "firebase-admin/firestore";

let app: App;

const serviceKey = require("@/service_key.json");
if (!serviceKey || typeof serviceKey !== "object") {
  throw new Error("Service key is missing or not a valid object");
}

// Fix the private key newlines if necessary.
if (serviceKey.private_key) {
  serviceKey.private_key = serviceKey.private_key.replace(/\\n/g, "\n");
}

if (getApps().length === 0) {
  console.log("Initializing Firebase Admin...");
  app = initializeApp({
    credential: cert(serviceKey),
  });
} else {
  console.log("Reusing existing Firebase Admin instance...");
  app = getApp();
}

const adminDb = getFirestore(app);
export { app as adminApp, adminDb };

---

5. Test Adding a Document

With these adjustments, try adding a document again. The function might look like this:

TYPESCRIPTCopied
import { adminDb } from "@/firebase-admin";
import { auth } from "@clerk/nextjs/server";

export async function createNewDocument() {
  const { sessionClaims } = await auth();
  
  if (!sessionClaims || !sessionClaims.email) {
    throw new Error("No valid session or email found in sessionClaims");
  }
  
  const docCollectionRef = adminDb.collection("documents");
  const data = { title: "New Doc" };

  // This should pass as data is a valid object.
  if (!data || typeof data !== "object") {
    throw new Error("Invalid payload: Data must be an object");
  }

  // Add document to 'documents' collection.
  const docRef = await docCollectionRef.add(data);

  // Create a subcollection under 'users'
  await adminDb
    .collection("users")
    .doc(sessionClaims.email)
    .collection("rooms")
    .doc(docRef.id)
    .set({
      userId: sessionClaims.email,
      role: "owner",
      createdAt: new Date(),
      roomId: docRef.id,
    });

  return { docId: docRef.id };
}

---

Summary

The error about the payload being null is usually a hint that something expected (like the service key or part of your data) isn’t loaded correctly. By ensuring:

• The service key file is correctly imported and its private key is properly formatted.
• Clerk’s session claims include the needed fields.
• And that you’re running on the Node.js runtime,

you should be able to resolve the errors and successfully add documents to Firestore.

Try these adjustments and let me know if you continue to face issues!