Troubleshooting your unified labeling on-premises scanner deployment

Applies to: Azure Information Protection, Windows Server 2019, Windows Server 2016, Windows Server 2012 R2

Relevant for: AIP unified labeling client only.

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.

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.

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

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 Microsoft Information Protection (MIP) 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 MIP labels and label policies, see Create and configure sensitivity labels and their policies in the Microsoft 365 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 your labeling admin center, such as the Microsoft 365 Security & Compliance Center, do the following:

- Define a default sensitivity label
- Define automatic / recommended labeling rules
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 365 Security & Compliance Center.

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.

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:

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:

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 on Best practices for deploying and using the AIP UL scanner.