How to fix auth/claims-too-large: Custom claims payload exceeds 1000-byte limit in Firebase

FirebaseINTERMEDIATEMEDIUM

This error occurs when attempting to set custom claims on a Firebase user that exceed the 1000-byte size limit. Firebase restricts custom claims to keep authentication tokens lightweight and performant.

What this error means

This error is thrown by Firebase Authentication when you try to set custom claims on a user account that exceed the 1000-byte limit. Custom claims are additional key-value pairs added to a user's ID token to implement role-based access control or store authorization metadata. Firebase enforces this limit because custom claims are embedded in the JWT (JSON Web Token) that gets sent with every authenticated request. Since tokens are transmitted with each API call to Firebase services (Firestore, Storage, Functions, etc.), larger tokens increase network overhead and can degrade application performance. The 1000-byte limit applies to the entire serialized JSON object of custom claims, not individual claim values. This includes the JSON structure itself (braces, quotes, commas), so the actual data you can store is slightly less than 1000 bytes.

How to fix "auth/claims-too-large: Custom claims payload exceeds 1000-byte limit"

1Measure your current claims size

Calculate how many bytes your claims object is using:

typescript

import * as admin from 'firebase-admin';

async function checkClaimsSize(uid: string) {
  const user = await admin.auth().getUser(uid);
  const claims = user.customClaims || {};
  const claimsString = JSON.stringify(claims);
  const byteSize = Buffer.byteLength(claimsString, 'utf8');

  console.log('Claims:', claims);
  console.log('Size:', byteSize, 'bytes');
  console.log('Remaining:', 1000 - byteSize, 'bytes');

  return byteSize;
}

This helps you understand how close you are to the limit and identify which claims consume the most space.

2Reduce claims to minimal identifiers

Keep only essential authorization data in custom claims. Use simple role names or IDs instead of full objects:

Bad approach (too large):

typescript

await admin.auth().setCustomUserClaims(uid, {
  role: 'admin',
  permissions: ['read', 'write', 'delete', 'manage-users', 'manage-roles'],
  metadata: {
    department: 'Engineering',
    team: 'Backend',
    location: 'San Francisco',
    manager: '[email protected]'
  },
  features: {
    betaAccess: true,
    premiumFeatures: ['feature1', 'feature2', 'feature3']
  }
});

Good approach (minimal):

typescript

await admin.auth().setCustomUserClaims(uid, {
  role: 'admin',
  dept: 'eng',
  premium: true
});

Store detailed information in Firestore and reference it when needed.

3Move large data to Firestore

Store comprehensive user data in Firestore and use custom claims only for access control:

typescript

// Set minimal claims for authorization
await admin.auth().setCustomUserClaims(uid, {
  role: 'admin',
  orgId: 'org_123'
});

// Store detailed user data in Firestore
await admin.firestore().collection('userProfiles').doc(uid).set({
  permissions: ['read', 'write', 'delete', 'manage-users'],
  metadata: {
    department: 'Engineering',
    team: 'Backend',
    location: 'San Francisco',
    manager: '[email protected]'
  },
  features: {
    betaAccess: true,
    premiumFeatures: ['feature1', 'feature2', 'feature3']
  }
});

In your client code, fetch additional data when needed:

typescript

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

async function getUserData() {
  const user = getAuth().currentUser;
  const token = await user?.getIdTokenResult();

  // Access minimal claims from token
  const role = token?.claims.role;
  const orgId = token?.claims.orgId;

  // Fetch detailed data from Firestore
  const profileDoc = await getDoc(doc(db, 'userProfiles', user.uid));
  const profile = profileDoc.data();

  return { role, orgId, ...profile };
}

4Optimize claim keys and values

Use shorter key names and abbreviations to save space:

typescript

// Before (74 bytes)
{
  "isAdministrator": true,
  "organizationIdentifier": "org_12345",
  "subscriptionLevel": "premium"
}

// After (43 bytes) - saves 31 bytes
{
  "admin": true,
  "org": "org_12345",
  "sub": "premium"
}

For arrays, use numeric IDs or codes instead of descriptive strings:

typescript

// Before (85 bytes)
{
  "permissions": ["read-users", "write-users", "delete-users"]
}

// After (32 bytes) - saves 53 bytes
{
  "perms": [1, 2, 3]  // Map codes to permissions in your app
}

5Implement a claims validation function

Create a helper function that validates claims size before setting them:

typescript

import * as admin from 'firebase-admin';

const MAX_CLAIMS_SIZE = 1000;

async function setCustomClaimsSafely(
  uid: string,
  claims: Record<string, any>
): Promise<void> {
  const claimsString = JSON.stringify(claims);
  const byteSize = Buffer.byteLength(claimsString, 'utf8');

  if (byteSize > MAX_CLAIMS_SIZE) {
    throw new Error(
      'Claims size (' + byteSize + ' bytes) exceeds limit (' + MAX_CLAIMS_SIZE + ' bytes). ' +
      'Reduce claims by ' + (byteSize - MAX_CLAIMS_SIZE) + ' bytes.'
    );
  }

  await admin.auth().setCustomUserClaims(uid, claims);
  console.log('Claims set successfully (' + byteSize + '/' + MAX_CLAIMS_SIZE + ' bytes)');
}

// Usage
try {
  await setCustomClaimsSafely(uid, { role: 'admin', org: 'org_123' });
} catch (error) {
  console.error('Failed to set claims:', error.message);
  // Fall back to storing in Firestore
}

How to fix auth/claims-too-large: Custom claims payload exceeds 1000-byte limit in Firebase

What this error means

Typical symptoms

Common causes

How to fix "auth/claims-too-large: Custom claims payload exceeds 1000-byte limit"

Advanced notes

Related errors

Official resources & further reading