Repair-SPCMismatchUser¶

SYNOPSIS¶

Repairs "User ID Mismatch" issues by safely removing the stale User Information List (UIL) entry and restoring permissions to the new identity.

SYNTAX¶

Repair-SPCMismatchUser [-InputObject] <PSCustomObject[]> [-Mode <String>] [-CreateSnapshot] [-SnapshotPath <String>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION¶

The Repair-SPCMismatchUser cmdlet implements Microsoft's recommended workflow for resolving Site User ID Mismatches, with added intelligence to automatically preserve and restore both Web-level and List-level permissions.

When a mismatched user is passed to this cmdlet, it will: 1. Validate that the user's UPN exists as an active object in Entra ID. 2. Deep-scan the site to extract all direct Web role assignments and unique List role assignments for the user. 3. (Optional) Create a JSON backup snapshot of these permissions. 4. Remove the stale user entry from the site's User Information List. 5. Re-grant all previously held Web and List permissions to the user. SharePoint automatically maps these new permission assignments to the user's correct, current Entra ID Object ID.

This completely resolves the "Access Denied" issue for the user without requiring them to manually request permissions again.

EXAMPLES¶

Example 1: Preview repairs (ReportOnly)¶

Get-SPCMismatchUser -AllSites | Where-Object Status -eq 'StaleIdentity' | Repair-SPCMismatchUser

Since -Mode defaults to ReportOnly, this will simply log what actions would be taken without making any changes.

Example 2: Clean and restore permissions¶

Get-SPCMismatchUser -SiteUrl "https://contoso.sharepoint.com/sites/Marketing" | 
    Where-Object Status -eq 'StaleIdentity' | 
    Repair-SPCMismatchUser -Mode CleanAndRestore

Scans the Marketing site for mismatched users, removes their stale UIL entries, and automatically restores all their permissions.

Example 3: Clean and restore with a snapshot backup (Pro feature)¶

$mismatches = Get-SPCMismatchUser -AllSites | Where-Object Status -eq 'StaleIdentity'
$mismatches | Repair-SPCMismatchUser -Mode CleanAndRestore -CreateSnapshot -SnapshotPath "C:\Mismatches" -Force

Repairs all mismatched users across the tenant. Before removing the stale UIL entries, it saves a JSON backup of their permissions to C:\Mismatches. Suppresses confirmation prompts with -Force.

PARAMETERS¶

`-InputObject`¶

One or more SPC.MismatchUser objects, typically generated by Get-SPCMismatchUser.

Type: PSCustomObject[]
Parameter Sets: (All)
Aliases: None

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

`-Mode`¶

Specifies the remediation action to take. - ReportOnly: (Default) Logs the intended actions but makes no changes. - Clean: Removes the stale UIL entry but does NOT restore permissions. - CleanAndRestore: Removes the stale UIL entry and automatically re-grants all direct permissions to the new Entra identity.

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: Named
Default value: ReportOnly
Accept pipeline input: False
Accept wildcard characters: False

`-CreateSnapshot`¶

If specified, exports a JSON snapshot of the user's direct permissions and group memberships before removing them from the UIL. This feature requires a Pro or Consultant license.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: None

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

`-SnapshotPath`¶

The directory where JSON snapshot files will be saved if -CreateSnapshot is used. If not provided, defaults to .\SPClean_Snapshots\[timestamp].

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

`-Force`¶

Suppresses confirmation prompts when running in Clean or CleanAndRestore modes.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: None

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

OUTPUTS¶

`SPC.MismatchRepairResult`¶

Returns an object summarizing the repair action, including the SiteUrl, UPN, RemovedFromUIL, PermissionsRestored, and Status (Success or Failed).