Purview policy distribution errors: DLP and retention policies stuck pending or in error

A Purview policy does nothing until it has been synced and distributed to every location it targets. If distribution stalls or fails, retention isn't applied, labels don't appear and DLP rules don't fire, while the policy looks perfectly configured. In this post I'll show where distribution errors surface, what each documented message means, how to fix the location behind it, and how to retry and prove the policy is applied.

Symptoms#

In the Microsoft Purview portal, the Status section of the policy's details pane shows one of these messages. Microsoft documents them for retention and retention label policies:

We're still processing your policy
We couldn't find this location
The location is ambiguous
The site is locked
The location is out of storage
We can't process your policy
Something went wrong
We ran into a problem
Settings not found

In Security & Compliance PowerShell, DistributionStatus isn't Success and DistributionResults names a code such as PolicySyncTimeout or FailedToOpenContainer. Adding a mailbox can also fail with RecipientTypeNotAllowed (in the portal: "You can't apply a hold here").

Why it happens#

Sync and distribution are a prerequisite for enforcement, and Microsoft doesn't support policies that contain errors: resolve every error, or the policy may not work as intended. The documented causes:

Two habits make all of this worse: editing a policy again while it's still Pending, and pushing many small location changes one at a time instead of in a single request.

How to fix it#

1. Find every policy that isn't distributed#

Connect-IPPSSession
$ret = Get-RetentionCompliancePolicy | ForEach-Object { Get-RetentionCompliancePolicy -Identity $_.Name -DistributionDetail }
$dlp = Get-DlpCompliancePolicy | ForEach-Object { Get-DlpCompliancePolicy -Identity $_.Name -DistributionDetail }
@($ret) + @($dlp) | Where-Object DistributionStatus -ne "Success" | Format-Table Name,DistributionStatus -AutoSize

# Details for one policy
Get-RetentionCompliancePolicy -Identity "Finance - 10 years" -DistributionDetail |
  Select-Object -ExpandProperty DistributionResults

App-based retention policies (Teams private channels and Viva Engage, and in newer tenants Teams chats, Microsoft 365 Copilot and AI apps) use Get-AppRetentionCompliancePolicy with the same switch. Only act on DistributionResults when the status reports errors; Microsoft says warnings can be ignored. If connecting fails, see fixing Connect-IPPSSession errors.

2. Fix the location, in one update#

Match the code to the table. For deleted or duplicate locations, remove them; after a FailedToOpenContainer error, the service requires the bad locations to be removed in your next update anyway. Put all changes into a single command:

Set-RetentionCompliancePolicy -Identity "Finance - 10 years" `
  -RemoveSharePointLocation "https://contoso.sharepoint.com/sites/OldProject" `
  -RemoveExchangeLocation "former.user@contoso.com"

For a locked or full site, ask the SharePoint administrator to unlock it or raise its quota first; versions kept for retention can fill a site, as explained in the Preservation Hold library article. For RecipientTypeNotAllowed, take out the mailbox type the policy doesn't support. For "Settings not found", add a rule with New-RetentionComplianceRule (or New-AppRetentionComplianceRule).

3. Retry distribution#

In the portal, select the policy name (not its checkbox) to open the details pane and choose Retry. In PowerShell:

Set-RetentionCompliancePolicy -Identity "Finance - 10 years" -RetryDistribution
Set-DlpCompliancePolicy -Identity "DLP - Customer data" -RetryDistribution

-RetryDistribution has its own parameter set, so run it on its own rather than combined with other changes. The policy returns to Pending; leave it alone until that clears.

4. Check the limits#

A tenant supports up to 10,000 policies of any kind, DLP and sensitivity label policies included. Within that, retention-type policies are capped per workload (for example 1,800 for Exchange, and 13 for SharePoint or OneDrive policies covering all sites). Policies with a static scope also cap specific inclusions or exclusions, for example 1,000 mailboxes or 100 SharePoint sites per policy. If you're near a limit, split the policy or move to adaptive scopes.

5. DLP-specific traps#

• SharePoint sites can't be added to a DLP policy until they've been indexed.
• Scope OneDrive by users or groups, not by site URLs.
• Don't pipe locations through ForEach-Object when adding or removing them; pass the full list in one call.
• Distribution isn't the last step everywhere: changes can take up to four hours to reach Microsoft 365 Copilot, and devices have their own policy sync status (see endpoint DLP device status).

6. A policy stuck deleting#

If deleting a retention policy fails and it stays in PendingDeletion, force it: Remove-RetentionCompliancePolicy -Identity "Old policy" -ForceDeletion.

Verify the fix#

• Rerun the step 1 script: the policy is gone from the list and DistributionStatus reads Success.
• The portal Status section shows no error for the policy.
• Prove behavior, not just status: test retention as in retention policies not applying, and trigger a test DLP match from a pilot account.

Prevent it next time#

• Check the status before every edit and wait while it says Pending.
• Batch location changes into one request.
• When you delete sites or mailboxes, remove them from static-scope policies in the same change.
• Run the step 1 script on a schedule and treat any non-success status as a ticket.
• For more retention messages, see the retention, records and audit errors quick reference.

References#

• Resolve errors in Microsoft 365 retention and retention label policies (Microsoft Learn)
• Identify errors in Microsoft 365 retention and retention label policies (Microsoft Learn)
• Limits for retention policies and retention label policies (Microsoft Learn)