Knowledge Base

KB 022202

Description

Opsole Migrate requires outbound HTTPS (port 443) connectivity to Opsole API and Microsoft cloud endpoints during migration. If any of these endpoints are unreachable, the affected operation fails and migration cannot continue.

The following error messages indicate a network connectivity issue. The specific message depends on which endpoint or operation is affected.

Error Messages:

Opsole API unreachable:

The remote server returned an error: (404) Not Found.

Microsoft Identity or Graph endpoints unreachable:

Authentication with the identity service failed. Error: Unable to connect to the remote server

Error contacting Microsoft Graph API to validate user

Error occurred while querying Autopilot object

Failed to delete Autopilot object

Failed to fetch source user Entra details or no user found

Failed to retrieve LAPS information

Failed to delete device from Entra

Required Endpoints

All endpoints require outbound HTTPS (port 443). If any of these are blocked, the corresponding operation will fail.

Cause

Resolution

1. Verify connectivity to all required endpoints. Run the following commands from an elevated PowerShell prompt on the affected device:

   Test-NetConnection opsole.com -Port 443
   Test-NetConnection login.microsoftonline.com -Port 443
   Test-NetConnection graph.microsoft.com -Port 443
   Test-NetConnection device.login.microsoftonline.com -Port 443

   If any test returns TcpTestSucceeded : False, the endpoint is blocked and must be allowed through the firewall or proxy.

2. Verify DNS resolution. If connectivity tests fail, confirm the device can resolve the endpoints:

   Resolve-DnsName opsole.com
   Resolve-DnsName login.microsoftonline.com
   Resolve-DnsName graph.microsoft.com

   If resolution fails, check DNS server configuration, DNS filtering policies, and split DNS rules.

3. Check proxy and SSL inspection. If the device uses a web proxy, ensure the required endpoints are allowed and not subject to SSL inspection. Verify proxy configuration:

   netsh winhttp show proxy

   If SSL inspection is in use, add exceptions for the endpoints listed above. SSL inspection that breaks the Microsoft certificate chain will cause authentication failures even when connectivity is confirmed.

4. Confirm Opsole API backend status. If all Microsoft endpoint tests succeed but the Opsole API test fails with TcpTestSucceeded : True, the issue may be an Opsole backend disruption. Contact Opsole Support and provide the migration logs for further investigation.

5. Retry the operation. After restoring connectivity, retry the operation.

KB 022203

Description

This error occurs when Opsole Migrate attempts to authenticate with Microsoft Entra ID (Azure AD) to acquire an access token, but the App Registration credentials are invalid, expired, or misconfigured. Migration cannot continue without a valid access token.

Error Message:

Error:"invalid_client","error_description":"AADSTS7000215: Invalid client secret provided."

Cause

Resolution

1. Verify client secret expiry. In the Entra admin portal, navigate to: App registrations > [Your App] > Certificates & secrets > Client secrets. Check the expiry date of the configured secret. If expired, generate a new client secret and update the value in the Opsole Migrate portal.

   The client secret value is only displayed once at the time of creation. Copy and store it securely immediately after generating.

2. Confirm secret value vs secret ID. Verify that the value stored in the Opsole Migrate portal is the client secret value, not the client secret ID. These are two different fields in the Entra portal. The secret ID is a GUID identifier; the secret value is the actual credential string.

3. Verify Application (Client) ID. Confirm the Application (Client) ID configured in the Opsole Migrate portal matches the App Registration in Entra ID: App registrations > [Your App] > Overview > Application (client) ID.

4. Verify Tenant ID. Confirm the Tenant ID configured in the Opsole Migrate portal matches the correct Entra ID tenant: App registrations > [Your App] > Overview > Directory (tenant) ID.

5. Confirm App Registration is enabled. In the Entra admin portal, navigate to: App registrations > [Your App] > Properties. Ensure Enabled for users to sign-in is set to Yes.

6. Check Conditional Access policies. Verify that no Conditional Access policy is blocking authentication for the App Registration service principal. Review policies under: Entra admin center > Protection > Conditional Access > Policies. Look for policies targeting workload identities or service principals that may block the app.

7. Re-run validation. After updating the configuration, re-run the App Registration validation to confirm that access token acquisition is successful.

KB 022204

Description

This error occurs when Opsole Migrate is unable to retrieve the Local Administrator Password Solution (LAPS) information for the device from Microsoft Graph. LAPS retrieval is performed to back up the local administrator credentials before migration.

Error Message:

Failed to retrieve LAPS Informations, Error:

Cause

Resolution

1. Verify Graph API permissions. In the Entra admin portal, navigate to: App registrations > [Your App] > API permissions. Confirm that DeviceLocalCredential.Read.All (Application type) is listed. If missing, add the permission.

2. Grant Admin Consent. On the same API permissions page, verify that the Status column shows Granted for [tenant]. If not, click Grant admin consent and confirm. This requires Global Administrator or Privileged Role Administrator privileges.

3. Confirm Windows LAPS is enabled. Verify that Windows LAPS is deployed to the device. For Intune-managed devices, check: Intune admin center > Endpoint security > Account protection > LAPS policies. For Group Policy-managed devices, verify the LAPS CSP or GPO is applied:

   Get-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Policies\LAPS" -ErrorAction SilentlyContinue

   If no LAPS policy exists, Windows LAPS must be configured before LAPS retrieval will work.

4. Check if LAPS password has been escrowed. Verify a LAPS password exists for the device in Entra ID: Entra admin center > Devices > All devices > [Device] > Local administrator password recovery. If no password is listed, the device has not yet completed a LAPS password rotation. Trigger a manual rotation:

   Reset-LapsPassword

5. Confirm Windows LAPS vs Legacy LAPS. If the environment uses legacy Microsoft LAPS (passwords stored in Active Directory ms-Mcs-AdmPwd attribute), Microsoft Graph cannot retrieve these credentials. The environment must be migrated to Windows LAPS (Entra ID based) for Graph API retrieval to work. To check which LAPS is in use:

   # Check for Windows LAPS
   Get-LapsAADPassword -DeviceIds <device-object-id> -ErrorAction SilentlyContinue
   
   # Check for Legacy LAPS (AD attribute)
   Get-ADComputer -Identity <hostname> -Properties ms-Mcs-AdmPwd | Select ms-Mcs-AdmPwd

6. Verify network connectivity and authentication. If none of the above apply, the issue may be network or authentication related. See:

   • KB 022233 — Network Connectivity Failures for endpoint reachability
   • KB 022203 — Authentication Failed — AADSTS7000215 for App Registration credential issues

7. Retry the operation. After completing the above checks, retry the operation.

KB 022205

Description

Opsole Migrate performs several local system operations during migration including registry read/write, scheduled task creation, certificate store management, user profile enumeration, SID resolution, and BitLocker queries. If any of these operations are blocked or fail, the affected step fails and migration cannot continue.

The following error messages indicate a local operation failure. The specific message depends on which operation is affected.

Error Messages:

Registry operations:

Failed to update the following Device entries

User profile registry entry not found

Multi-profile write failed for SID

Critical failure during multi-profile collection

Error during MDM cleanup

Scheduled task:

Error creating InterMigrate task

Certificate store:

Failed to remove MDM certificate

User and system queries:

Failed to resolve SID for user

Failed to retrieve BitLocker recovery key

Cause

Resolution

1. Whitelist Opsole Migrate in EDR and antivirus. Add the following folder and all its contents to the EDR and antivirus exclusion list:

   C:\ProgramData\OpsoleMigrate\

   Additionally, whitelist Opsole Migrate using the Opsole code-signing certificate, which can be downloaded from the Opsole Migrate portal.

2. Review endpoint hardening policies. Check if any of the following are blocking Opsole Migrate operations:

   • ASR rules — Check for rules blocking registry writes or process creation from untrusted sources
   • Tamper Protection — May prevent registry or system modifications
   • WDAC / AppLocker — May block execution of Opsole Migrate executables or PowerShell operations

   To check ASR rules in effect:

   Get-MpPreference | Select-Object -ExpandProperty AttackSurfaceReductionRules_Ids

3. Repair WMI repository (if system queries fail). If the error is related to SID resolution or system information queries, the WMI repository may be corrupted:

   winmgmt /verifyrepository

   If verification reports inconsistency:

   winmgmt /salvagerepository

4. Retry the operation. After completing the above checks, retry the operation.

KB 022206

Description

This error occurs when Opsole Migrate locates the provisioning package (PPKG) but installation fails and the device is not joined to Entra ID. The provisioning package contains the bulk enrollment token required for automated Entra ID Join during migration. Migration cannot continue without a successful Entra Join.

Error Message:

Failed to install provisioning package

Cause

Resolution

1. Verify Conditional Access exclusions. In the Entra admin center, navigate to: Protection > Conditional Access > Policies. Ensure the provisioning account used for bulk enrollment is excluded from any Conditional Access policies enforcing MFA or location-based restrictions on device registration. Specifically check policies targeting:

   • All cloud apps or Microsoft Intune Enrollment
   • Register or join devices action
   • All users grant controls requiring MFA

2. Check provisioning package expiry. Verify the provisioning package was generated recently and the bulk token has not expired. If expired, regenerate the provisioning package from the Opsole Migrate portal and redeploy to the device.

3. Verify provisioning package integrity. Install the provisioning package manually on a test device and confirm the device is able to complete Entra ID Join. This will confirm whether the PPKG file itself is valid and working. If the test device joins successfully, the issue is environment-specific to the affected device.

4. Check Entra ID device registration settings. In the Entra admin center, navigate to: Devices > Device settings.

   • Confirm "Users may join devices to Microsoft Entra ID" is set to All or includes the provisioning account.
   • Check "Maximum number of devices per user" and confirm the provisioning account has not reached the limit.

5. Verify device is not already Entra Joined. Check the current join state on the device:

   dsregcmd /status

   If AzureAdJoined : YES is already showing, the device is already joined. If it is joined to a different tenant, the existing join must be removed before the provisioning package can be installed.

6. Verify MDM auto-enrollment configuration. In the Entra admin center, navigate to: Mobility (MDM and WIP) > Microsoft Intune. Confirm the MDM user scope is set to All or includes the provisioning account user group.

7. Verify network connectivity. Ensure the device can reach the required Microsoft endpoints for device registration. See KB 022233 — Network Connectivity Failures for the full endpoint list and validation commands.

8. Retry the operation. After completing the above checks, regenerate the provisioning package if needed and retry the operation.

KB 022208

Description

This error occurs when Opsole Migrate attempts to unjoin the device from Active Directory using the configured domain disjoin account, but the operation fails with an "Access is denied" error. Migration is rolled back and cannot continue.

Error Message:

Operation encountered a critical failure in module Remove-Computer. Recent actions have been reverted. StatusCode: False
Failed to unjoin <HOSTNAME> from domain gracefully. Error: Failed to unjoin computer '<HOSTNAME>' from domain '<DOMAIN>' with the following error message: Access is denied.

Cause

Resolution

1. Verify domain disjoin account credentials. Confirm the account credentials configured in the Opsole Migrate portal are correct and current. To validate, attempt a manual unjoin from an elevated PowerShell prompt on the test device:.

  Remove-Computer -UnjoinDomainCredential (Get-Credential) -Force -Verbose

If this succeeds, the issue is specific to the credential stored in the portal. If it fails with the same error, the issue is at the AD or GPO level.

2. Check account lockout status. Verify the disjoin account is not locked out in Active Directory:

   Get-ADUser -Identity <disjoin_account> -Properties LockedOut | Select LockedOut

   If locked, unlock the account and investigate the source of the lockouts.

3. Verify OU-level permissions. Confirm the disjoin account has Delete Computer Objects permission on the OU where the target device resides. If permissions are scoped to specific OUs, verify the device has not been moved to a different OU.

4. Review endpoint security controls. Ensure endpoint security or hardening policies do not block domain unjoin operations. Allow-list Opsole Migrate if applicable.

5. Review Group Policy restrictions. Check the effective GPO on the device for restrictions under: Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment > Remove computer from docking station. Ensure the disjoin account or its group is included.

6. Retry the operation. After completing the above checks, retry the operation.

KB 022209

Description

This error occurs when Opsole Migrate attempts to unjoin the device from Active Directory, but the operation fails because NTLM authentication is disabled or blocked on the device. Migration is rolled back and cannot continue.

Error Messages:

Failed to unjoin <HOSTNAME> from domain. Error: Failed to unjoin computer '<HOSTNAME>' from domain '<DOMAIN>' with the following error message: Authentication failed because NTLM authentication has been disabled., Terminating Migration process.....

Cause

Remove-Computer relies on NTLM authentication internally. If NTLM is restricted or blocked at the device level, the unjoin fails regardless of whether the credentials are correct. NTLM restriction policies applied via Group Policy remain cached locally on the device even when it is offline and no longer receiving GPO updates.

Resolution

1. Verify domain disjoin account credentials. Confirm the account credentials configured in the Opsole Migrate portal are correct and current. To validate, attempt a manual unjoin from an elevated PowerShell prompt on the test device:

   Remove-Computer -UnjoinDomainCredential (Get-Credential) -Force -Verbose

   If this succeeds with the correct credentials, update the credentials in the portal and retry.

2. Enable NTLM locally via registry. If credentials are confirmed correct, or the device has no line of sight to AD, remove the NTLM restriction locally on the device:

   Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0" -Name "RestrictSendingNTLMTraffic" -Value 0

   Retry the migration after applying this change.

3. Check NTLM restriction policies. Verify whether NTLM is restricted by Group Policy or local security policy:

   Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Security Options

   To check the effective setting:

   gpresult /h gpresult.html

4. Review endpoint security controls. Ensure endpoint security tools or hardening agents are not blocking NTLM authentication at the OS layer.

5. Retry the operation. After completing the above checks, retry the operation.

KB 022210

Description

During migration, certain failures may require manual intervention or a recovery procedure to restore the device to a working state. These situations typically occur when a migration phase fails partway through execution, leaving the device in an intermediate state such as a locked screen, a missing login prompt, or an incomplete Entra Join.

This article provides a quick reference to common recovery scenarios and links to the detailed step-by-step troubleshooting and recovery guide.

Common Recovery Scenarios

Troubleshooting and Recovery Guide

For detailed step-by-step recovery procedures with screenshots for each scenario listed above, refer to the full troubleshooting guide:

OpsoleMigrate — Troubleshooting Guide