How to Fix Automatic Retention Labels Not Applying in SharePoint Online
Question details
Users are experiencing issues where automatic retention labels based on KQL are not successfully applying to targeted files in SharePoint Online.
- Product
- SharePoint Online
- Device & OS
- not provided
- Scenario
- Configuring automatic document retention policies using Key Query Language (KQL) to manage file lifecycles.
- Observed behavior
- Retention labels fail to assign to the intended SharePoint Online files, often due to syntax errors, scope settings, or backend processing delays.
Ensure you have the necessary administrative privileges in the Microsoft 365 Compliance Center and verify that your tenant's licensing supports automatic retention policies.
Verify KQL Syntax, Conditions, and Wait for the Weekly Backend Process
Check your KQL syntax for precision, ensure all conditions are met, and allow up to a week for the SharePoint background process to assign the labels.
Automatic retention labels in SharePoint Online rely on a background backend process to identify matching files and apply the corresponding labels. This process does not run instantaneously; it typically runs on a weekly schedule.
Log in to the Microsoft 365 Compliance Center as an administrator and navigate to the Information Governance or Records Management section.
Select your automatic retention label policy and verify that the content type and site scope match the SharePoint target locations.
Examine your KQL query carefully. Ensure you are using the exact capitalization required and that property values are enclosed in single quotation marks according to official KQL guidelines.
Save any syntax corrections. Wait up to seven days for the weekly background process to successfully execute and apply the labels to your files.
Try WPS Office for Seamless Document Management
While troubleshooting complex Microsoft 365 and SharePoint administrative policies, consider WPS Office as a lightweight, free alternative for your daily document creation and editing. It delivers high compatibility with Office formats without the heavy resource usage.
- 1. Download the installer: Visit the official WPS Office website and download the free version for your operating system.
- 2. Install and launch: Run the installation file and open the WPS Office desktop application.
- 3. Manage your documents: Easily open, edit, and save your existing Microsoft Office documents with seamless formatting compatibility.
Frequently Asked Questions
How long does it take for automatic retention labels to apply in SharePoint Online?
The backend process that assigns automatic retention labels to files in SharePoint Online generally runs on a weekly basis. After configuring or updating a policy, it can take up to seven days for the labels to be fully applied.
Why is my KQL query failing to trigger the retention label?
Common issues preventing KQL queries from working include incorrect syntax capitalization, missing single quotation marks around property values, incorrect site scopes, or mismatched content types.
Do I need a specific Microsoft 365 license to use automatic retention labels?
Yes, deploying automatic retention labels based on queries or trainable classifiers typically requires an advanced compliance license, such as a Microsoft 365 E5 license or equivalent add-on.
