A retention policy looks right in the Microsoft Purview portal, yet expired Teams messages are still on screen, a OneDrive keeps files nobody can delete, or eDiscovery can't find what the policy should have kept. Usually retention is working as designed, just not where or when you expected. In this post I'll show how retention runs behind Teams, SharePoint and OneDrive, how to tell a real fault from normal timing, and how to prove what a policy is doing.
Errors this guide fixes
We've deleted older messages due to your org's retention policyTeams client (chat)This message has been deleted because of a Retention PolicyTeams client (channel conversation)File not foundTeams client (file shared in a message)
Symptoms#
- Teams messages older than the retention period are still visible days after they should have expired, or they've gone from Teams but eDiscovery still returns them.
- Users see one of these system messages, sometimes in chats with people from another organization:
We've deleted older messages due to your org's retention policy
This message has been deleted because of a Retention Policy- A file shared in a Teams message still shows a preview, but opening it returns
File not found: the file had its own, shorter retention. - SharePoint or OneDrive content survives the end of the period, deleted files never reach the Preservation Hold library, or users get an error when they try to delete a library, list or site.
Why it happens#
Retention acts on compliance copies, through timer jobs, and only in the locations a policy names. Five causes cover most cases:
| Cause | What you see |
|---|---|
| Wrong location. Teams chats and Teams channel messages are separate locations. Exchange mailbox policies don't cover Teams messages, Teams policies don't cover files, and retention labels aren't supported for Teams messages. | Messages or files never expire, or expire on another schedule |
Timer jobs. Teams: a timer job, which typically takes 1–7 days to run, moves expired messages to the hidden SubstrateHolds folder, keeps them at least a day, then deletes them on a later run. SharePoint and OneDrive: the timer job can take up to seven days; Preservation Hold library cleanup takes up to 37 days, then up to 93 days in the recycle bins. | Content lingers well past the configured period |
| Holds and conflicts. Retention wins over deletion and the longest retention period wins. Litigation Hold, delay hold, an eDiscovery hold or another retention policy for the same location suspends permanent deletion. | Content gone from the app but still in eDiscovery |
| Distribution. The policy is still pending or has errors for some locations. | Nothing happens for some users or sites |
| Unsupported targets. Sites that aren't indexed or are locked, room mailboxes, guests' shadow mailboxes, users in another tenant, users without a suitable license. | Retention silently skips those items |
Two Teams behaviors surprise most admins. A message a user deletes vanishes from Teams at once but only moves to SubstrateHolds after 21 days. And when one organization's policy deletes a message, Teams removes it for everyone in the conversation, including external participants, whose own copies stay searchable.
How to fix it#
1. Confirm the policy is distributed and targets the right locations#
Connect-IPPSSession
# Channel messages, SharePoint, OneDrive and older Teams chats policies
Get-RetentionCompliancePolicy -Identity "Teams channels - 3 years" -DistributionDetail |
Format-List Name, Enabled, DistributionStatus, *Location*
Get-RetentionComplianceRule -Policy "Teams channels - 3 years" |
Format-List Name, RetentionDuration, RetentionComplianceAction
# Newer Teams chats, private channel, Viva Engage and Copilot policies
Get-AppRetentionCompliancePolicy -Identity "Teams chats - 1 year" -DistributionDetail |
Format-List Name, Applications, DistributionStatus, *Location*DistributionStatus should read Success; otherwise fix the locations first (see policy distribution errors). Then match location to content:
- Chats need the Teams chats location and channel messages the Teams channel messages location. After the 2025 private channel migration, private channel messages are stored in group mailboxes and follow the channel messages location; older policies for the private channel location keep enforcing.
- Files from channels live in SharePoint (Microsoft 365 Group mailboxes & sites, or SharePoint sites). Files and meeting recordings from chats need a policy that includes the organizer's OneDrive account.
2. Look up every policy that applies#
In Data Lifecycle Management or Records Management, open Policy lookup and enter the exact email address, group address or site URL (OneDrive accounts count as sites; no wildcards). Every policy listed affects the outcome.
3. Find holds that suspend deletion#
Connect-ExchangeOnline
# Chats are stored in each participant's mailbox, channel messages in the team's group mailbox
Get-Mailbox -Identity adele@contoso.com |
Format-List LitigationHoldEnabled, InPlaceHolds, DelayHoldApplied
Get-Mailbox -GroupMailbox -Identity sales-team@contoso.com | Format-List InPlaceHolds
Get-OrganizationConfig | Select-Object -ExpandProperty InPlaceHoldsOrganization-wide mailbox and group policies appear only on the organization config, and newer Teams chats, private channel and Copilot policies don't stamp these properties at all; use Policy lookup for them. Decode the GUIDs as shown in retention policies vs litigation hold and check eDiscovery cases for holds. A hold explains "gone from Teams but still in eDiscovery"; that's expected, not a fault.
4. Rule out site and account prerequisites#
- SharePoint sites must be indexed for retention to apply. Hiding a library from search results doesn't exclude its files.
- Check for a lock with
Get-SPOSite -Identity https://contoso.sharepoint.com/sites/Finance | Select-Object Url, LockState; items in a NoAccess or ReadOnly site can't be deleted. - Retention policies cover files in document libraries, not list items or the libraries and folders themselves. Turn on versioning if every version must be kept.
- Teams users need a license that covers retention for Teams, such as Office 365 E3 or A3.
5. Do the timing math before escalating#
A Teams message can stay visible for up to seven days after it expires, and a delete-after-one-day policy can take 16 days to remove it from eDiscovery results. For SharePoint and OneDrive, allow up to seven days for a new policy to apply, then the 37-day and 93-day windows above. Don't keep editing the policy while you wait; every change has to distribute again.
Verify the fix#
- The policy shows
DistributionStatus : Success, and Policy lookup lists the expected policies for a test user and site. - Verify Teams retention with an eDiscovery search, not the Teams app: search the user's mailbox or the team's group mailbox for a known test message. Edited and deleted copies are returned until permanent deletion, then disappear.
- In SharePoint, edit and then delete an existing test file in a covered site; the original should appear in the Preservation Hold library. A brand-new file isn't copied on its first edit.
- For delete actions, check again after the expected deletion window.
Prevent it next time#
- Treat Teams chats, channel messages and files as three separate decisions, and use adaptive scopes where membership changes.
- Brief the help desk on the two Teams system messages before go-live; they can't be customized.
- Before deleting a leaver's account, decide whether their Teams data must be kept; a user in a retaining Teams policy becomes an inactive mailbox.
- Watch storage in the Preservation Hold library, and look up status messages in the retention, records and audit errors quick reference.
