Unable to restore backup

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

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

This issue occurs because Tableau Server needs to run the identity migration. The migration is necessary to populate the Identity Service, an identity schema Tableau Server 2022.1 (and later) uses to provision and authenticate users. To prevent any potential issues, the upgrade process can't proceed when Tableau Server detects that the Tableau Server backup uses a different identity schema than Tableau Server 2022.1 (or later).

To resolve this issue, follow the steps described below.

Step 1: Enable legacy-idenity-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 pending-changes apply

    Important: After the backup is restored, the migration populates the Identity Service with identity information.

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.

  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

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.

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.

Thanks for your feedback!