Troubleshooting post-migration contribution and membership mapping

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

During placeholder user reassignment, you might encounter the following issues.

Source user reassignment failed

To retry reassignment for source users with failed status, you can use the GraphQL API or the Rails console. For more information, see issue 589777. UI support is discussed in issue 593001.

Use the GraphQL API

{{< history >}}

• Introduced in GitLab 18.11.

{{< /history >}}

Use the importSourceUserRetryFailedReassignment mutation to retry a failed reassignment:

mutation {
  importSourceUserRetryFailedReassignment(input: { id: "gid://gitlab/Import::SourceUser/<SOURCE_USER_ID>" }) {
    importSourceUser {
      id
      status
    }
    errors
  }
}

Replace <SOURCE_USER_ID> with the import source user ID. You can find this ID by querying importSourceUsers on the namespace.

Use the Rails console

You can manually retry failed source users in the Rails console:

# Find by the source user's placeholder user ID because placeholder user IDs are easy to fetch from the UI
placeholder_user_id = <PLACEHOLDER_USER_ID>
import_source_user = Import::SourceUser.find_by(placeholder_user_id: placeholder_user_id)

if import_source_user.failed?
  import_source_user.update!(status: Import::SourceUser::STATUSES[:reassignment_in_progress])
  Import::ReassignPlaceholderUserRecordsWorker.perform_async(import_source_user.id)
  puts "Reassignment retry queued"
else
  puts "Import source user status: #{import_source_user.status} (expected 'failed')"
end

Investigate repeated failures

If the source user fails again, check importer.log for any logs with the message Failed to reassign placeholder user to begin investigating the root cause.

Source user reassigned successfully but its placeholder user was not deleted

Placeholder users are deleted after successfully reassigning user contributions. However, some database records that reference the placeholder user's ID might still exist in the database after reassignment, preventing the placeholder user from being deleted. When this happens, administrators can still see placeholder users in the administrator user table. Although placeholder users do not count towards license limits and have no effect on typical GitLab operations, some administrators might prefer to have all placeholder users deleted after migrating.

Users reassigning placeholder users in GitLab 18.5 and earlier are more likely to encounter this scenario. When this happens, the message Unable to delete placeholder user because it is still referenced in other tables appears in importer.log tied to the placeholder user's ID.

To delete these users, you can either:

• Delete the placeholder user as an administrator. This approach is best when you're confident any remaining placeholder user contributions can be deleted.
• Upgrade the GitLab instance to GitLab 18.6 or later and retry placeholder reassignment for the placeholder user in the Rails console. This approach is best when reassignment completed on GitLab 18.5 or earlier and you're unsure about what placeholder user contributions remain.

To retry a completed placeholder user's reassignment in the Rails console:

# Find the placeholder user's source user
placeholder_user_id = <PLACEHOLDER_USER_ID>
import_source_user = Import::SourceUser.find_by(placeholder_user_id: placeholder_user_id)

if import_source_user.completed?
  import_source_user.update!(status: Import::SourceUser::STATUSES[:reassignment_in_progress])
  Import::ReassignPlaceholderUserRecordsWorker.perform_async(import_source_user.id)
  puts "Reassignment retry queued"
else
  puts "Import source user status: #{import_source_user.status} (expected 'completed')"
end