Your Teams retention policy is configured but messages remain in chats and channels long after the deletion period. This happens because Teams retention policies only apply to messages that meet specific conditions, and several settings can block deletion entirely. This article explains why retention policies fail and shows you how to verify and fix the configuration in the Teams admin center.
You will learn the exact steps to check policy scope, confirm assignment, and test deletion behavior. You will also see common failure patterns and how to avoid them.
Key Takeaways: Fix Teams Retention Policy Deletion Failures
- Teams admin center > Data lifecycle management > Microsoft 365 retention: Shows the actual retention policy settings that control message deletion.
- Retention policy scope assignment: Determines which users or teams the policy applies to; unassigned policies do nothing.
- Retention settings > Delete items older than: Sets the deletion period; a period of zero days deletes immediately after the message is sent.
- PowerShell cmdlet Get-RetentionCompliancePolicy: Verifies the policy assignment and effective settings when the admin center shows no errors.
Why Teams Retention Policy Does Not Delete Messages
Teams retention policies are managed by Microsoft Purview, not by the Teams admin center itself. The Teams admin center only shows a link to the Purview portal. When you create a retention policy in Purview, it applies to Teams messages only if you select the correct locations: Teams channel messages and Teams chats.
Deletion fails for several reasons. The policy may be set to retain items only, with no deletion action. The policy may be assigned to no users or groups. Or the policy may be scoped to a specific set of users that does not include the people whose messages you expect to be deleted.
Another common cause is the coexistence of two retention policies. When two policies apply to the same message, the longer retention period wins. If one policy retains messages for 7 years and another deletes after 30 days, the message stays for 7 years.
Finally, Teams messages are not deleted instantly. Purview processes deletion in a background job that can take up to 7 days after the retention period expires. If you check immediately after the period ends, messages still appear.
How Retention Policies Interact with Teams Storage
Teams messages are stored in Exchange mailboxes for chats and in SharePoint and OneDrive for files shared in channels. Retention policies for Teams messages actually apply to the underlying Exchange items. If the Exchange mailbox is inactive or has litigation hold enabled, deletion is blocked.
Steps to Diagnose and Fix Retention Policy Deletion in Teams
Follow these steps in order. Each step addresses a specific cause of deletion failure.
- Open the retention policy in Microsoft Purview
Go to the Microsoft Purview compliance portal at purview.microsoft.com. In the left navigation, select Data lifecycle management, then Microsoft 365 retention. Find the policy that should delete Teams messages. Click the policy name to open its details. - Verify the retention action is set to delete
In the policy details, look for the Retention settings section. Confirm the action says Delete items older than, not Retain items for a specific period. If the policy only retains, deletion never happens. Edit the policy and change the action to delete if needed. - Check the retention period value
Ensure the period is not set to Forever. If you want messages deleted after 30 days, set the value to 30 days. A value of 0 days deletes messages almost immediately after they are sent, but note that the background job still takes time. - Confirm the policy is assigned to the right users or teams
In the policy details, scroll to Locations. You must see Teams channel messages and Teams chats listed as Included. If they show Excluded, the policy does not apply. Click Edit and add the specific users or groups. For channel messages, you can also scope to specific teams. - Check for overlapping policies
In the same Microsoft 365 retention page, list all policies. Look for any other policy that includes Teams locations and has a longer retention period. The longest retention period always wins. If two policies conflict, edit the one with the shorter period to match your intent, or remove the conflicting policy. - Verify the policy assignment with PowerShell
Connect to Exchange Online PowerShell and run Get-RetentionCompliancePolicy -Identity “Your Policy Name” | Format-List. Check the Enabled, Mode, and ExchangeLocation properties. If Mode shows Enforce, the policy is active. If it shows Test, deletion is not enforced. Change the mode to Enforce with Set-RetentionCompliancePolicy. - Wait for the deletion job to run
After confirming all settings, wait up to 7 days. Purview runs deletion in batches. Check the message again after 48 hours and after 7 days. If messages still appear after 7 days, check the mailbox for holds. - Check for litigation hold or eDiscovery hold
In the Exchange admin center, go to Recipients > Mailboxes. Select the user mailbox and look for Litigation hold in the Mailbox features section. If enabled, deletion is blocked. Disable the hold or exclude the mailbox from the retention policy scope.
If Teams Retention Policy Still Does Not Delete Messages
Teams Shows a Policy Error in the Admin Center
The Teams admin center sometimes displays a warning that a retention policy is invalid. This usually means the policy was created in Purview but does not include any Teams locations. Go to Purview and edit the policy to add Teams channel messages and Teams chats. Then refresh the Teams admin center.
Messages Are Deleted in Chats but Not in Channels
Channel messages are stored in SharePoint, not Exchange. If your policy only includes Teams chats, channel messages remain. Edit the policy in Purview and add Teams channel messages as a location. Also verify that the SharePoint site associated with the team is not under a separate retention policy that overrides yours.
Retention Policy Applies to Some Users but Not Others
A policy scoped to specific users will not affect users outside that scope. In Purview, edit the policy and check the Included list under Locations. If you want the policy to apply to all users, select All users. If you want to include a new group, add it to the scope.
Deletion Happens but Not on the Exact Date
Purview does not guarantee deletion on the exact day the period ends. The background job runs periodically, so deletion can occur a few days after the period. This is normal. Check again after 7 days before assuming the policy is broken.
Teams Retention Policy Settings vs Common Misconfigurations
| Item | Correct Setting | Common Misconfiguration |
|---|---|---|
| Retention action | Delete items older than | Retain items for a specific period |
| Locations | Teams channel messages and Teams chats included | Only Exchange email included |
| Scope | All users or specific groups that need deletion | No users assigned |
| Mode | Enforce | Test mode |
| Overlapping policies | Only one policy with Teams locations | Two policies with different periods |
Conclusion
You can now diagnose why a Teams retention policy fails to delete messages. Start by checking the retention action, the period, and the location scope in Purview. Then verify the policy mode with PowerShell and check for holds on the mailbox.
After confirming all settings, wait up to 7 days for the deletion job to run. If messages still remain, check for litigation hold or overlapping policies. Use the PowerShell cmdlet Get-RetentionCompliancePolicy to confirm the policy is enforced, and remember that the longest retention period always wins in a conflict.