How to fix auth/uid-already-exists: User ID already in use by another user in Firebase

import { getAuth } from 'firebase-admin/auth';

// ❌ This will fail if uid already exists
try {
  const userRecord = await getAuth().createUser({
    uid: 'custom-user-123',
    email: '[email protected]',
    password: 'securePassword123'
  });
} catch (error: any) {
  console.error('Failed:', error.code); // auth/uid-already-exists
}

import { getAuth } from 'firebase-admin/auth';

async function createUserSafely(uid: string, email: string, password: string) {
  try {
    // Check if user already exists
    const existingUser = await getAuth().getUser(uid);
    console.log('User already exists:', existingUser.uid);
    return { success: false, error: 'User already exists' };
  } catch (error: any) {
    if (error.code === 'auth/user-not-found') {
      // User doesn't exist, safe to create
      const userRecord = await getAuth().createUser({
        uid: uid,
        email: email,
        password: password
      });
      console.log('User created successfully:', userRecord.uid);
      return { success: true, uid: userRecord.uid };
    }
    throw error;
  }
}

await createUserSafely('custom-user-123', '[email protected]', 'password');

import { getAuth } from 'firebase-admin/auth';

// ❌ Custom UID may already exist
await getAuth().createUser({
  uid: 'user-' + userId,  // Risky - may conflict
  email: '[email protected]',
  password: 'password'
});

import { getAuth } from 'firebase-admin/auth';

// ✅ Firebase generates unique UID automatically
const userRecord = await getAuth().createUser({
  email: '[email protected]',
  password: 'password'
});

console.log('User created with auto-generated UID:', userRecord.uid);

// Store the Firebase UID in your database for future reference
await database.collection('users').doc(userRecord.uid).set({
  email: userRecord.email,
  createdAt: new Date()
});

import { getAuth } from 'firebase-admin/auth';
import { v4 as uuidv4 } from 'uuid';

// Generate truly unique UIDs
const uniqueId = `legacy_${Date.now()}_${Math.random().toString(36).substring(7)}`;

// Or use UUID
const uuidBasedId = `user_${uuidv4()}`;

await getAuth().createUser({
  uid: uniqueId,
  email: '[email protected]'
});

import { getAuth } from 'firebase-admin/auth';

const usersToImport = [
  { uid: 'user-1', email: '[email protected]', passwordHash: hashBuffer1 },
  { uid: 'user-2', email: '[email protected]', passwordHash: hashBuffer2 }
];

// ❌ May fail if any uid already exists
const result = await getAuth().importUsers(usersToImport);

import { getAuth } from 'firebase-admin/auth';

async function importUsersWithValidation(usersToImport: any[]) {
  // Get all existing UIDs to filter
  const existingUids = new Set();
  let pageToken: string | undefined;

  do {
    const page = await getAuth().listUsers(100, pageToken);
    page.users.forEach(user => {
      existingUids.add(user.uid);
    });
    pageToken = page.pageToken;
  } while (pageToken);

  // Filter to only new users
  const newUsers = usersToImport.filter(user => !existingUids.has(user.uid));

  if (newUsers.length === 0) {
    console.log('All users already exist in Firebase');
    return { success: false, message: 'No new users to import' };
  }

  // Import only new users
  const result = await getAuth().importUsers(newUsers);

  console.log(`Imported ${result.successCount} users`);
  console.log(`Failed: ${result.failureCount} users`);

  if (result.errors.length > 0) {
    result.errors.forEach(err => {
      console.error(`Failed to import user at index ${err.index}: ${err.error.message}`);
    });
  }

  return { success: true, result };
}

await importUsersWithValidation(usersToImport);

import { getAuth } from 'firebase-admin/auth';

// ❌ Will fail with auth/uid-already-exists
const userRecord = await getAuth().createUser({
  uid: 'user-123',
  email: '[email protected]'
});

import { getAuth } from 'firebase-admin/auth';

async function createOrUpdateUser(uid: string, email: string, displayName?: string) {
  try {
    // Check if user exists
    const existingUser = await getAuth().getUser(uid);

    // User exists, update instead
    const updatedUser = await getAuth().updateUser(uid, {
      email: email,
      displayName: displayName || existingUser.displayName
    });

    console.log('User updated:', updatedUser.uid);
    return { action: 'updated', user: updatedUser };

  } catch (error: any) {
    if (error.code === 'auth/user-not-found') {
      // User doesn't exist, create new
      const newUser = await getAuth().createUser({
        uid: uid,
        email: email,
        displayName: displayName
      });

      console.log('User created:', newUser.uid);
      return { action: 'created', user: newUser };
    }

    throw error;
  }
}

await createOrUpdateUser('user-123', '[email protected]', 'John Doe');

import { getAuth } from 'firebase-admin/auth';

interface UserCreationOptions {
  uid: string;
  email: string;
  displayName?: string;
  password?: string;
  maxRetries?: number;
}

async function createUserWithRetry(options: UserCreationOptions) {
  const { uid, email, displayName, password, maxRetries = 3 } = options;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      // Check if user already exists
      try {
        const existingUser = await getAuth().getUser(uid);
        return {
          success: false,
          error: 'User already exists',
          existingUser: {
            uid: existingUser.uid,
            email: existingUser.email,
            createdAt: existingUser.metadata.creationTime
          }
        };
      } catch (error: any) {
        if (error.code !== 'auth/user-not-found') {
          throw error;
        }
      }

      // Create user
      const userRecord = await getAuth().createUser({
        uid: uid,
        email: email,
        displayName: displayName,
        password: password
      });

      console.log(`User created successfully (attempt ${attempt}): ${userRecord.uid}`);

      return {
        success: true,
        user: {
          uid: userRecord.uid,
          email: userRecord.email,
          createdAt: userRecord.metadata.creationTime
        }
      };

    } catch (error: any) {
      if (error.code === 'auth/uid-already-exists') {
        console.warn(`UID already exists (attempt ${attempt}/${maxRetries})`);

        if (attempt === maxRetries) {
          return {
            success: false,
            error: 'UID already exists and maximum retries exceeded',
            code: 'auth/uid-already-exists'
          };
        }

        // Wait before retry
        await new Promise(resolve => setTimeout(resolve, 100 * attempt));

      } else if (error.code === 'auth/invalid-argument') {
        return {
          success: false,
          error: 'Invalid user data provided',
          details: error.message
        };
      } else {
        throw error;
      }
    }
  }
}

// Usage
const result = await createUserWithRetry({
  uid: 'custom-user-123',
  email: '[email protected]',
  displayName: 'John Doe',
  password: 'securePassword123'
});

console.log(result);