Troubleshoot Issues with the Identity Migration

Applies to: Tableau Server

Unable to restore backup

After upgrading to Tableau Server 2022.1 (or later), restoring a Tableau Server backup might cause the following error:

“The backup cannot be restored because Tableau Server uses the new identity service tables by default.”

This issue might occur when Tableau Server needs to run the identity migration, which is a necessary process to populate the Identity Service. The Identity Service is an identity schema that was introduced beginning with Tableau Server 2022.1 and is used to provision and authenticate users. To prevent any potential issues, the restore process can't proceed when Tableau Server detects that the Tableau Server backup uses a different identity schema than the version that it's being restored to.

Note: The Identity Service is the default identity schema in Tableau Server version 2022.1-2022.1.7, 2022.3-2022.3.9, and 2023.1-2023.15.

To resolve this issue, follow the steps described below.

Step 1: Enable legacy-identity-mode and restore the backup

  1. Open a command prompt as an administrator on the initial node (where TSM is installed) in the cluster.

  2. Set Tableau Server 2022.1 (or later) to use the legacy identity store mode by running the following commands:

    tsm authentication legacy-identity-mode enable
    tsm pending-changes apply

    Tableau Server must use the legacy identity store mode to populate the Identity Service. For more information about the tsm command, see tsm authentication legacy-identity-mode.

  3. Restore the backup again to enable the migration to initiate by running the following commands:

    tsm maintenance restore --file <file_name>
    tsm start

    Important: After the backup is restored, the migration populates the Identity Service with identity information. For general information about restoring from backup, see Restore from a Backup.

Step 2: Validate and complete the identity migration

  1. Sign in to Tableau Server as an administrator.

  2. From the left navigation pane, select Users (or All Sites > Users for a multi-site Tableau Server) and then click the Identity Migration page to verify the migration has started.

    You can monitor and manage its progress using the dedicated Identity Migration page available from Tableau Server’s Users page. For more information, see Manage the Identity Migration.

  3. Resolve or acknowledge all identity conflicts as described in Resolve Identity Migration Conflicts so that All failures tab displays "0" like in the image below.

  4. Do one of the following:

    • To run the identity migration job now, next to the Migration Overview heading, click the Edit Schedule drop-down arrow, and then select Run Now.

    • Alternatively, you can wait for the migration job to run during the next scheduled time.

  5. After the migration completes, from the Identity Migration page, validate that the Migration Overview shows 100% complete.

Step 3: Configure Tableau Server to use the Identity Service

  1. Open a command prompt as an administrator on the initial node (where TSM is installed) in the cluster.

  2. Run the following commands:

    tsm authentication legacy-identity-mode disable
    tsm pending-changes apply

    Note: After running the commands above, the dedicated Identity Migration page is removed and no longer accessible. The page is accessible only when tsm authentication legacy-identity-mode is enabled.

After Tableau Server is configured to use the Identity Service, when users sign in to Tableau Server, Tableau Server searches for their user identities using their identifiers in the configured identity store. From the identifiers, the universal unique identifiers (UUID) are returned and used to match existing Tableau Server user identities. This process then generates sessions for the users and completes the authentication workflow.

“Unexpected error” on Identity Migration page

After resolving or acknowledging all user identities from the Identity Migration page, you see an “Unexpected error” message. This message can display when you’ve tried to resolve or acknowledge more than 1000 user identities at one time.

To resolve this issue, select and resolve or acknowledge 1000 or less user identities, and then try again.

For more information about managing identity conflicts, see Resolve Identity Migration Conflicts.

Migration progress appears unresponsive or stuck

If the migration status or migration progress bar appears unresponsive or stuck, validate that you have resolved and acknowledged all user conflicts under Migration failures.

To resolve this issue, ensure all conflicts are resolved and acknowledged by selecting one or more users identities in the All failures tab and clicking Acknowledge from the Actions drop-down menu. Perform this task until the All failures tab displays "0." For more information about managing identity conflicts, see Resolve Identity Migration Conflicts.

Note: After all identity conflicts have been resolved or addressed, all migration jobs have to run before you can enable the Identity Service for Tableau Server. You can run the migration jobs now by clicking the Edit Schedule drop-down arrow next to the Migration overview heading, and then selecting Run Now. When the Migration Overview shows 100% complete, you can configure Tableau Server to use the Identity Service. For more information, see Step 3: Complete the identity migration.

"Identity migration is in progress" pop-up persists

The "identity migration is in progress" notification persists despite completing the identity migration because the Identity Service has not been enabled yet. To complete the identity migration the Identity Service needs to be enabled in Step 4: Configure Tableau Server to use the Identity Service so that Tableau Server can use the identity structure that enables identity pools capability.

Identity Migration page disappears

When the identity migration is complete and Tableau Server is configured to use the Identity Service, the dedicated Identity Migration page is removed and no longer accessible. The Identity Migration page is needed only for the identity migration or when tsm authentication legacy-identity-mode is enabled.

Users can't sign in

After the identity migration has completed and the Identity Service enabled, some users are unable to sign in to Tableau Server. In most cases, this issue occurs to users whose identities had conflicts and were subsequently Acknowledged during the identity migration. Users identities that were acknowledged are not migrated to the Identity Service and subsequently ignored during Active Directory (AD) or LDAP group syncs going forward.

If users associated with those acknowledged user identities require access to Tableau Server again, manually add the users to Tableau Server. After the users are manually added, subsequent AD or LDAP group syncs recognize the user identities and sync as expected.

Revert identity migration

If there are issues, such as certain users not being able to sign in to Tableau Server, that you believe are caused by the Identity Service, you can use the tsm authentication legacy-identity-mode command to revert back to use the legacy identity store mode. After reverted, both new users who were added after the identity migration and users who could only sign in to Tableau Server before the migration are able to sign in to Tableau Server without any issues.

After reverting from the Identity Service to the legacy identity store mode, you can use the Identity Migration page to run the migration for the problematic user identities. For more information about managing identity conflicts, see Resolve Identity Migration Conflicts.

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!