How to fix auth/invalid-user-import: User record being imported is malformed in Firebase

FirebaseINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 91 views

This Firebase Authentication error occurs when importing user accounts with malformed data. The error indicates that one or more user records in your import file don't meet Firebase's validation requirements. Common issues include missing required fields, invalid field formats, or data type mismatches.

Quick fix

Fixes auth/invalid-user-import: User record being imported is malformed

  1. Validate your user import data structure
  2. Check for common data format issues
  3. Use the Firebase Admin SDK validation tools
  4. Fix malformed records and retry import
  5. Handle large imports with batching
firebase — error
# auth/invalid-user-import: User record being imported is malformed
auth/invalid-user-import: User record being imported is malformed

What this error means

The "auth/invalid-user-import" error in Firebase Authentication occurs when you're using the Firebase Admin SDK to import user accounts in bulk, and one or more user records in your import data are malformed or invalid. Firebase provides a user import feature through the Admin SDK that allows you to migrate users from other authentication systems or perform bulk operations. When importing users, each record must adhere to specific validation rules including required fields, proper field formats, correct data types, and Firebase constraints.

Typical symptoms

  • Firebase Admin SDK user import operation fails with "auth/invalid-user-import" error
  • Bulk user migration from another authentication system fails
  • Error appears when calling auth.importUsers() method in Firebase Admin SDK
  • Import operation stops partway through with this error message
  • Firebase console logs show "User record being imported is malformed"
  • Only some users are imported while others fail

Common causes

  1. Missing required fields in user import data (most common)
  2. Invalid email format in user records
  3. Malformed password hash or salt for migrated passwords
  4. Invalid phone number format (not E.164)
  5. UID contains invalid characters or is too long
  6. Custom claims with invalid JSON structure
  7. User metadata fields with incorrect data types
  8. Duplicate UIDs in the import data
  9. User provider data with missing required fields
  10. Timestamp fields with invalid date formats

How to fix "auth/invalid-user-import: User record being imported is malformed"

1Validate your user import data structure

First, ensure your user import data follows Firebase's required structure. Each user record should include required fields like UID, and optional fields like email, phoneNumber, etc. must be properly formatted. Key validation points include: UID must be present and max 128 characters with only alphanumeric and certain symbols; email must be valid format if provided; phone must be E.164 format if provided; booleans must be true/false, not strings; timestamps must be ISO 8601 format.

2Check for common data format issues

Examine your import data for common formatting problems: Email validation - ensure emails have proper format (user@example.com); Phone number validation - must be E.164 format (+12345678901); Password hash validation - must be Buffer if migrating passwords; UID validation - must be 1-128 characters, only alphanumeric, hyphen, underscore, period.

3Use the Firebase Admin SDK validation tools

Firebase Admin SDK provides tools to validate user import data before attempting the actual import. Use auth.importUsers() with dryRun: true to validate without importing. This will return success/failure counts and detailed error messages for each problematic record. You can also validate individual fields programmatically by checking UID length/format, email regex, phone format, and boolean fields.

4Fix malformed records and retry import

After identifying problematic records, fix them and retry the import. Create a clean import function with error handling that tracks successful imports and failed users. Implement retry logic with exponential backoff. Common fixes include: trimming whitespace from string fields, ensuring boolean fields are actual booleans, converting UIDs to strings, and fixing format issues.

5Handle large imports with batching

For large user imports, use batching to avoid timeouts and memory issues. Implement batch import function that processes users in configurable batch sizes (start with 100-500). Add delays between batches to avoid rate limiting. Monitor memory usage during imports and adjust batch size accordingly. Track progress and handle partial failures gracefully.

6Verify imported users and clean up

After successful import, verify the users by fetching user records with auth.getUser(uid). Check a sample of imported users to ensure they were created correctly. Clean up temporary files and data used during the import process. Log import statistics including total time, success rate, and common error types for future reference.

Advanced notes

Firebase has specific requirements for user import data that differ from regular user creation. When migrating users with passwords, you must provide properly formatted passwordHash and passwordSalt. UIDs must be unique across your entire Firebase project and cannot be changed once set. Custom claims are limited to 1000 bytes when serialized as JSON. For performance, tune batch size based on memory usage and implement rate limiting handling. Always design for partial failure and implement idempotent retry logic. Use service accounts with minimal permissions and encrypt sensitive import data.

Frequently asked questions

What does "auth/invalid-user-import: User record being imported is malformed" mean?
The "auth/invalid-user-import" error in Firebase Authentication occurs when you're using the Firebase Admin SDK to import user accounts in bulk, and one or more user records in your import data are malformed or invalid. Firebase provides a user import feature through the Admin SDK that allows you to migrate users from other authentication systems or perform bulk operations. When importing users, each record must adhere to specific validation rules including required fields, proper field formats, correct data types, and Firebase constraints.
How do I fix "auth/invalid-user-import: User record being imported is malformed"?
This Firebase Authentication error occurs when importing user accounts with malformed data. The error indicates that one or more user records in your import file don't meet Firebase's validation requirements. Common issues include missing required fields, invalid field formats, or data type mismatches.
What causes "auth/invalid-user-import: User record being imported is malformed"?
Missing required fields in user import data (most common) Invalid email format in user records Malformed password hash or salt for migrated passwords
Is the "auth/invalid-user-import: User record being imported is malformed" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading