Solving "Duplicate Username" SAML Login Warning in Mattermost

Applies To: Mattermost Self-Hosted (Enterprise Edition)
Error Example:

WARN Unable to update existing SAML user. Allowing login anyway.
Error 1062 (23000): Duplicate entry 'username' for key 'Users.Username'

Problem

When attempting SAML login, a warning appears in the logs indicating a duplicate username or conflicting AuthData, even if the Mattermost database does not show actual duplicates in Users.Username.

Cause

This issue can occur if:

• A user has multiple accounts (e.g., due to ID changes or duplicate provisioning).

• The AuthData field (used for SAML identity matching) is incorrectly assigned or overlaps with another account.

• Manual database changes or a mismatch in SAML attributes causes Mattermost to misassociate accounts.

Recommended Resolution

Step 1: Use mmctl to Reset the AuthData

Run the following command to clear the AuthData for the affected SAML user(s):

mmctl saml auth-data-reset --users <user_id_1>,<user_id_2> --include-deleted

• Replace <user_id_1> and <user_id_2> with the actual user IDs (not usernames).

• You can retrieve user IDs using:

mmctl user search <username>

🔎 The --include-deleted flag ensures the reset applies even to deactivated users with conflicting data.

Step 2: Retry SAML Login

After resetting the AuthData, attempt SAML login again. Mattermost will populate the AuthData field based on the configured IdAttribute from your SAML provider.

Make sure the IdAttribute is correctly set (e.g., Username, Email, etc.) and matches what your Identity Provider sends.

Validation

To confirm the reset was successful:

1. Check the AuthData field in the database:

   SELECT Username, AuthData FROM Users WHERE Id = '<user_id>';
   

2. The AuthData should either be cleared or updated to match the SAML attribute after login.

⚠️ Important Notes

• Avoid manually editing the Mattermost database unless directed by support.

• mmctl saml auth-data-reset works only with user IDs — not usernames or email addresses.

• The field is automatically updated on successful login if the reset was applied.

🔗 Related Links

• mmctl: SAML Auth Data Reset

• SAML Configuration in Mattermost

• Switching Authentication Methods