/flags /purview/set-retentioncompliancepolicy-retrydistribution

Set-RetentionCompliancePolicy -RetryDistribution: redeploy a retention policy with errors

updated 2026-10-24

tool: Microsoft Purview (Security & Compliance PowerShell)
command: Set-RetentionCompliancePolicy
flag: -RetryDistribution
default: off (a policy is distributed once when created or changed)

Set-RetentionCompliancePolicy -Identity NAME -RetryDistribution asks Microsoft Purview to distribute a retention policy again to the Exchange Online and SharePoint locations where the first distribution failed. It is the documented fix for policies that show errors such as "Something went wrong", "We're still processing your policy" or "We ran into a problem" in the Purview portal. The reference: "The RetryDistribution switch specifies whether to redistribute the policy to all Exchange Online and SharePoint locations... Locations whose initial distributions succeeded aren't included in the retry. Policy distribution errors are reported when you use this switch."

powershell

Connect-IPPSSession -UserPrincipalName admin@contoso.com
Get-RetentionCompliancePolicy -Identity "Finance retention" -DistributionDetail |
  Select-Object -ExpandProperty DistributionResults
Set-RetentionCompliancePolicy -Identity "Finance retention" -RetryDistribution
Get-RetentionCompliancePolicy -Identity "Finance retention" -DistributionDetail |
  Format-List Name, DistributionStatus

Read the status first

Get-RetentionCompliancePolicy -DistributionDetail fills the DistributionResults property; without the switch, the reference warns that "the values of the DistributionStatus and *Location property values will be inaccurate." Microsoft's troubleshooting article maps the portal messages to values in DistributionResults and to a fix:

Portal message	DistributionResults shows	Fix
Something went wrong	PolicyNotifyError	retry with -RetryDistribution
We're still processing your policy	PolicySyncTimeout	retry with -RetryDistribution
We can't process your policy	ActiveDirectorySyncError	retry with -RetryDistribution
We ran into a problem	InternalError	retry with -RetryDistribution
We couldn't find this location	FailedToOpenContainer	remove the location, then retry
The site is locked	SiteInReadOnlyOrNotAccessible	unlock the site, then retry

The last two need a change before the retry helps; see We couldn't find this location.

Syntax

-RetryDistribution is in a parameter set of its own: Set-RetentionCompliancePolicy [-Identity] <PolicyIdParameter> -RetryDistribution [-Confirm] .... In that set the switch is mandatory, which is why location changes such as -AddExchangeLocation cannot be combined with it.

Pitfalls

Connect to the right session. The cmdlet exists only after Connect-IPPSSession; without it PowerShell reports that it is not recognized (Connect-IPPSSession).
Role. You need a Purview role that manages retention, for example Compliance Administrator.
Retrying a deleted policy. A policy in PendingDeletion needs Remove-RetentionCompliancePolicy -ForceDeletion, not a retry (stuck in PendingDeletion).
Patience. Running the retry repeatedly does not make it faster; wait for the status to change.
App policies. Teams private channels and Viva Engage policies use Set-AppRetentionCompliancePolicy; the main retention cmdlets are on retention policy and label cmdlets.

FAQ

Can I change locations and use -RetryDistribution in the same command?

No. -RetryDistribution has its own parameter set with only -Identity and common parameters such as -Confirm. Change the locations first, then run a separate command with -RetryDistribution.

How long does a retry take?

Distribution is asynchronous and can take from minutes to a day or more for policies with many locations. Check DistributionStatus with Get-RetentionCompliancePolicy -DistributionDetail until it shows Success.

Does it work for retention label policies?

Microsoft's troubleshooting article applies the same Set-RetentionCompliancePolicy -RetryDistribution fix to policies listed under Label policies. Policies for Teams private channels and Viva Engage use the App cmdlets, such as Set-AppRetentionCompliancePolicy.

Sources

errors · purviewRetention policy error: We couldn't find this location (FailedToOpenContainer)A location in the retention policy no longer exists (FailedToOpenContainer). Remove it with Set-RetentionCompliancePolicy, then use -RetryDistribution.errors · purviewRetention policy stuck in PendingDeletion: Remove-RetentionCompliancePolicy -ForceDeletionA Purview retention policy stuck in PendingDeletion had a failed deletion. Connect-IPPSSession, then run Remove-RetentionCompliancePolicy with -ForceDeletion.commands · purviewPurview retention in PowerShell: New-RetentionCompliancePolicy, New-RetentionComplianceRule, New-ComplianceTagA retention policy is a policy plus a rule: New-RetentionCompliancePolicy sets locations, New-RetentionComplianceRule the duration. Labels: New-ComplianceTag.commands · purviewConnect-IPPSSession: connect to Security & Compliance PowerShell (Purview)Connect-IPPSSession from ExchangeOnlineManagement opens Security & Compliance PowerShell for Purview cmdlets; add -EnableSearchOnlySession for eDiscovery.