Troubleshooting your unified labeling on-premises scanner deployment
Note
The Azure Information Protection unified labeling scanner is being renamed Microsoft Purview Information Protection scanner. At the same time, configuration (currently in preview) is moving to the Microsoft Purview compliance portal. Currently, you can configure the scanner in both the Azure portal and the compliance portal. Instructions in this article refer to both admin portals.
Use the content in this article to help you troubleshoot your on-premises scanner deployment.
Troubleshooting using the scanner diagnostic tool
If you're having issues with the Azure Information Scanner, verify whether your deployment is healthy using the Start-AIPScannerDiagnostics PowerShell command:
Start-AIPScannerDiagnostics
The diagnostics tool checks the following details and then exports a log file with the results:
- Whether the database is up to date
- Whether network URLs are accessible
- Whether there's a valid authentication token and the policy can be acquired
- Whether the profile is defined in the Azure portal
- Whether offline/online configuration exists and can be acquired
- Whether the rules configured are valid
Tip
- If you are running the command under a user that is not the scanner user, be sure to add the -OnBehalf parameter.
- To print the last 10 errors from the scanner log, add the Verbose parameter. If you want to print more errors, use the VerboseErrorCount to define the number of errors you want to print.
Note
The Start-AIPScannerDiagnostics command does not run a full prerequisites check. If you're having issues with the scanner, also ensure that your system complies with scanner requirements, and that your scanner configuration and installation is complete.
Troubleshooting a scan that timed out
If the scanner stops unexpectedly while scanning a large number of files in a repository, you may need to modify one of the following settings:
Number of dynamic ports. You may need to increase the number of dynamic ports for the operating system hosting the files. Server hardening for SharePoint can be one reason why the scanner exceeds the number of allowed network connections, and therefore stops.
For more information about how to view the current port range and increase the range, see Settings that can be Modified to Improve Network Performance.
List view threshold. For large SharePoint farms, you may need to increase the list view threshold. By default, the list view threshold is set to 5,000.
For more information, see Manage large lists and libraries in SharePoint.
Verify scanning details per scanner node and repository
Use the Get-AIPScannerStatus together with variables to get details about the scanning status on each node in your scanner cluster.
Use one or more of the following methods:
- Use the NodesInfo variable to get details about the scanning status on each node
- Use the Verbose parameter to get data for current scan
Use the NodesInfo variable to get details about the scanning status on each node
For example, run the following command:
PS C:\> Get-AIPScannerStatus
Cluster : contoso-test
ClusterStatus : Scanning
StartTime : 12/22/2020 9:05:02 AM
TimeFromStart : 00:00:00:37
NodesInfo : {t-contoso1-T298-corp.contoso.com,t-contoso2-T298-corp.contoso.com}
The output displays details about the current scan status and a list of nodes in the cluster.
Use the NodesInfo variable to display further details about each node in the cluster:
PS C:\WINDOWS\system32> $x=Get-AIPScannerStatus
PS C:\WINDOWS\system32> $x.NodesInfo
The output displays details for each node in a table. For example:
NodeName Status IsScanning Summary
-------- -------- ---------- -------
t-contoso1-T298-corp.contoso.com Scanning True Microsoft.InformationProtection.Scanner.ScanSummaryData
t-contoso2-T298-corp.contoso.com Scanning Pending Microsoft.InformationProtection.Scanner.ScanSummaryData
To drill down further into each node, use the NodesInfo variable again, with the node integer starting with 0. For example:
PS C:\Windows\system32> $x.NodesInfo[0].Summary
The output displays a long list of details about the scan on the selected node. For example:
ScannerID : t-contoso1-T298-corp.contoso.com
ScannedFiles : 2280
FailedFiles : 0
ScannedBytes : 78478187
Classified : 0
Labeled : 0
....
Use the Verbose parameter to get data for current scan
PS C:\> Get-AIPScannerStatus -Verbose
ScannedFiles MBScanned CurrentScanSummary RepositoriesStatus
------------ --------- ------------------ ------------------
2280 78478187 Microsoft.InformationProtection.Scanner.ScanSummaryData {{ Path = C:\temp, Status = Scanning }
Drill down further to find more details for the repositories by using the RepositoriesStatus or the CurrentScanSummary variables.
Possible repository statuses include:
- Skipped, if the repository was skipped
- Pending, if the current scan hasn't yet started scanning the repository
- Scanning, if the current scan is running on the repository
- Finished, if the current scan has completed running on the repository
RepositoriesStatus
PS C:\Windows\system32> $x.Get-AIPScannerStatus -Verbose
PS C:\Windows\system32> $x.RepositoriesStatus
Path Status
---- ------
C:\temp Scanning
CurrentScanSummary
PS C:\Windows\system32> $x.CurrentScanSummary
ScannerID :
ScannedFiles : 2280
FailedFiles : 0
ScannedBytes : 78478187
Classified : 0
Labeled : 0
....
This output shows only a single repository. In cases of multiple repositories, each one will be listed separately.
Scanner error reference
Use the following sections to understand specific error messages generated by the scanner, and troubleshooting or solution actions to fix the issue:
Error type | Troubleshooting |
---|---|
Authentication errors | - Authentication token not accepted - Authentication token missing |
Policy errors | - Policy missing - Policy doesn't include any automatic labeling condition |
DB / Schema errors | - Database errors - Mismatched or outdated schema |
Other errors | - Underlying connection was closed - Stuck scanner processes - Unable to connect to remote server - Error occurred while sending the request - Missing content scan job or profile - No repositories are configured - No cluster found - Scanner diagnostics errors |
Authentication token not accepted
Error message
Microsoft.InformationProtection.Exceptions.AccessDeniedException: The service didn't accept the auth token.
Solution
If the Set-AIPAuthentication command failed, make sure to define the permissions correctly in the Azure portal.
For more information, see Create and configure Azure AD applications for Set-AIPAuthentication.
Authentication token missing
Error message
One of the following:
NoAuthTokenException: Client application failed to provide authentication token for HTTP request
Microsoft.InformationProtection.Exceptions.NoAuthTokenException: Client application failed to provide authentication token for HTTP request. Failed with: System.AggregateException: One or more errors occurred. ---> Microsoft.IdentityModel.Clients.ActiveDirectory.AdalException: user_interaction_required: One of two conditions was encountered: 1. The PromptBehavior.Never flag was passed, but the constraint could not be honored, because user interaction was required. 2. An error occurred during a silent web authentication that prevented the http authentication flow from completing in a short enough time frame
Failed to acquire a token using windows integrated authentication (No SSO)
From the Azure portal, on the Nodes page:
Policy does not include any automatic labeling condition
Solution
In order to have the scanner run non-interactively, you must authenticate using a token.
When you run the Set-AIPAuthentication command, make sure you use the token parameter on behalf of the scanner user.
For example:
$pscreds = Get-Credential CONTOSO\scanner
Set-AIPAuthentication -AppId "77c3c1c3-abf9-404e-8b2b-4652836c8c66" -AppSecret "OAkk+rnuYc/u+]ah2kNxVbtrDGbS47L4" -DelegatedUser scanner@contoso.com -TenantId "9c11c87a-ac8b-46a3-8d5c-f4d0b72ee29a" -OnBehalfOf $pscreds
Acquired application access token on behalf of CONTOSO\scanner.
For more information, see Get an Azure AD token for the scanner.
Policy missing
Error message
Policy is missing
Description
The scanner is unable to find your sensitivity label policy file.
Solution
To verify that your policy file exists as expected, check in the following location: %localappdata%\Microsoft\MSIP\mip\MSIP.Scanner.exe\mip\mip.policies.sqlite3
For more information about sensitivity labels and their label policies, see Create and configure sensitivity labels and their policies in the Microsoft Purview documentation.
Policy doesn't include any automatic labeling condition
Error
Errors show that your labeling policy is missing automatic labeling conditions
Solution
Verify any or all of following issues:
Solution | Details |
---|---|
Check your content scan job settings | In the Azure portal, do the following: - Set the Info types to be discovered to All - Define a default label to be applied when scanning |
Check your labeling policy settings | In the Microsoft Purview compliance portal, do the following: - Define a default sensitivity label - Configure automatic / recommended labeling |
Verify that your policy is accessible | If your settings are defined as expected, the policy file itself may be missing or inaccessible, such as when there's a timeout from the Microsoft Purview compliance portal. To verify your policy file, check that the following file exists: %localappdata%\Microsoft\MSIP\mip\MSIP.Scanner.exe\mip\mip.policies.sqlite3 |
For more information, see What is the Azure Information Protection unified labeling scanner? and Learn about sensitivity labels.
Database errors
Error message
DB error
Description
The scanner may not be able to connect to the database.
Solution
Check your network connectivity between the scanner computer and the database.
Additionally, make sure that the service account being used to run scanner processes has any permissions required to access the database.
Mismatched or outdated schema
Error message
One of the following:
SchemaMismatchException
In the Azure portal, on the Nodes page:
DB schema is not up to date. Run Update-AIPScanner command to update the DB schema
orError: DB schema is not up to date
Solution
Run the Update-AIPScanner command to resynchronize your schema and ensure that it's up to date with any recent changes.
Scanner diagnostics errors
If you get errors running the Start-AIPDiagnostics command, make sure that you're using the correct scanner account credentials in the -OnBehalf parameter.
For example:
$scanner_account_creds= Get-Credential
Start-AIPScannerDiagnostics -onbehalf $scanner_account_creds
Underlying connection was closed
Error message
System.Net.WebException: The underlying connection was closed: An unexpected error occurred on a send. ---> System.IO.IOException: Authentication failed because the remote party has closed the transport stream.
Solution
This error usually means that TLS 1.2 isn't enabled.
For more information, see:
- Firewalls and network infrastructure requirements
- How to enable TLS 1.2
- Enable TLS 1.1 and TLS 1.2 support in Office Online Server
Stuck scanner processes
Error message
Scanner is processing a single file longer than expected. The process might be stuck.
Solution
Check the detailed report to see whether the file is still growing or not.
If the file continues to grow, this means that the scanner is still processing data, and you must wait until it's done.
However, if the file is no longer growing, do the following:
Do one or both of the following:
- Run the Start-AIPScannerDiagnostics cmdlet to run diagnostic checks on your scanner, and export and zip log files for any errors that are found.
- Run the Export-AIPLogs cmdlet to export and zip log files from the %localappdata%\Microsoft\MSIP\Logs directory.
Create a dump file for the MSIP Scanner service. In the Windows Task Manager, right-click the MSIP Scanner service, and select Create dump file.
In the Azure portal, stop the scan.
On the scanner machine, restart the service.
Open a support ticket and attach the dump files from the scanner process.
For more information, see Troubleshooting a scan that timed out.
Unable to connect to remote server
Error
In the %localappdata%\Microsoft\MSIP\Logs\MSIPScanner.iplog file, Unable to connect to the remote server ---> System.Net.Sockets.SocketException: Only one usage of each socket address (protocol/network address/port) is normally permitted IP:port
Note
This file will be zipped if there are multiple logs.
Description
The scanner has exceeded the number of allowed network connections.
Solution
Increase the number of dynamic ports for the operating system hosting the files.
For more information about how to view the current port range and increase the range, see Settings that can be Modified to Improve Network Performance.
See also: Troubleshooting a scan that timed out.
Error occurred while sending the request
Error message
[System.Net.Http.HttpRequestException: An error occurred while sending the request. ---> System.Net.WebException: The underlying connection was closed: An unexpected error occurred on a send. ---> System.IO.IOException: Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host. ---> System.Net.Sockets.SocketException: An existing connection was forcibly closed by the remote host
Solution
This error usually means that TLS 1.2 isn't enabled.
For more information, see:
- Firewalls and network infrastructure requirements
- How to enable TLS 1.2
- Enable TLS 1.1 and TLS 1.2 support in Office Online Server
Missing content scan job or profile
Error
Errors show that your content scan job or profile can't be found.
For example, the following error in the Azure portal on the Nodes page: No content scan job found
Solution
Check your scanner configuration in the Azure portal.
For more information, see Configuring and installing the Azure Information Protection unified labeling scanner.
Note
A profile is a legacy scanner term that has been replaced by the scanner cluster and content scan job in newer versions of the scanner.
No repositories configured
Error message
In the admin portal, on the Nodes page: No repositories are configured
Description
You may have a content scan job with no repositories configured.
Solution
Check your content scan job settings and add at least one repository.
For more information, see Create a content scan job.
No cluster found
Error message
In the admin portal, on the Nodes page: No cluster found
Description
No actual match found for one of the scanner clusters you've defined.
Solution
Verify your cluster configuration and check it against your own system details for typos and errors.
For more information, see Create a scanner cluster.
Next steps
For more information, see our blog post Best practices for deploying and using the AIP UL scanner.
Feedback
Submit and view feedback for