Troubleshooting your unified labeling on-premises scanner deployment

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 in the middle unexpectedly and doesn't complete 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, as well as 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 has not 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 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 or Error: 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 is not 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:

1. 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.

2. 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.

3. In the Azure portal, stop the scan.

4. On the scanner machine, restart the service.

5. 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 is not 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 cannot 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 Azure 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 Azure 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.