This article provides options for migrating a Custom Database connection with disabled imports, like Legacy Authentication mode, to Import Mode when the database contains user profiles with non-unique email addresses.

• Custom Database Connections
• Import Mode

Database connections use email as a unique identifier by default. In a Custom Database configured for Legacy Authentication mode, the results from the database action scripts are the source of truth. This configuration allows the creation of Auth0 profiles with duplicate emails within the same connection. This duplication can cause issues with email-based flows and with reliably identifying the correct user during the automatic import flow.

There are three options to migrate the connection.

Option 1: Use the Non-Unique Emails Feature

If the use case requires non-unique emails, migrate to the non-unique email feature. Review the Non-Unique Emails documentation for detailed information.

• Limitations:

  • This requires creating a new connection, as the feature cannot be applied to existing databases as of September 2025.

  • Once enabled, it is not possible to disable the non-unique emails feature for that connection.

  • The feature requires the use of flexible identifiers.

  • Review all considerations in the Non-Unique Emails Considerations documentation before proceeding.

Option 2: Bulk Import to a New Connection with Unique Emails

If non-unique emails are not a requirement, bulk export the users and import them with updated, unique emails into a new connection. A new connection is required because it is not possible to upsert email addresses. Password hashes can be included in the bulk import for a smoother transition.

• Refer to the documentation for Bulk User Imports and importing Custom Password Hashes.

• Limitation: If custom user_ids have been used, this could cause conflicts with user ID-based API calls if the new connection's users have the same user_ids until the old database connection is deleted.

• Mitigation: To mitigate this, add a prefix to the new user_ids before importing. If it is essential to keep the same user_ids and there are concerns about deleting the original connection, proceed to Option 3.

Option 3: Migrate to Unique Emails in the Existing Connection

1. Update the custom database action scripts or the legacy database records to provide a unique and valid email address for each user.

2. Go to the connection's settings tab and enable Import Mode. When users next sign in, their email will be pulled from the login script callback and updated within their Auth0 profile.

To track migration, add a custom app_metadata flag to the users in the Custom Database login script's profile callback. This will overwrite existing metadata on the account when the user triggers the login script. If existing metadata must be preserved, use a post-login Action to check if the user was created (event.user.created_at) before the date Import Mode was enabled and add the app_metadata flag.

• Refer to the documentation for the Post-Login Event Object and how to Manage User Metadata with Actions.

• Limitation: After Import Mode is enabled, more than one user cannot sign in with the same email address. After one user is imported with email1@example.com, any other account that attempts to sign in with the same email will receive the following error:

  DB Login Custom script: imported user exists with email.

  Once a username or email is imported, all subsequent sign-in attempts using that identifier will not trigger the custom database scripts. Auth0 finds the record internally before triggering the scripts.

• Mitigations: To mitigate users entering non-unique email addresses during migration, use one of the following options:

  • Recommended: Enable Flexible Identifiers and Attributes and remove email as an identifier, leaving only username. This updates the Universal Login page to accept only usernames. Email flows, such as password resets, will still function if an email address is stored in the user profile. Email can be re-enabled as an identifier after the migration is complete.

  • Educate users to enter only their username until the migration is complete. Add logic to the login script to reject email input and only accept usernames to identify the correct account. For example:

    return callback(new WrongUsernameOrPasswordError(emailOrUsername, "Must enter username"));
    

  • For full control over the user interface, set up a custom Universal Login page that rejects email input entirely. This can be accomplished using the Advanced Customizations for Universal Login (ACUL) feature or a Custom Classic Login Page with Auth0.js.