OpsoleMigrate — Troubleshooting Guide

Issue 1: API Request Timeout

Root Cause

Intermittent connectivity issue or DNS issue from the client device, preventing it from reaching the Opsole API endpoints or Microsoft endpoints

Common Cause

Intermittent network or DNS resolution failure on the client device causing the migration process to silently fail without logging to the portal

Resolution

Close Opsole Migrate and reopen the application Click Start Preparation again If the issue persists: Verify internet connectivity Check DNS resolution Ensure access to Opsole API endpoints is not blocked

Reference For detailed troubleshooting steps, refer to: https://docs.opsole.com/docs/kb#kb-022202

Issue 2: Migration Failed — Error 500 or No Migration Log in Portal

Root Cause

Intermittent connectivity issue or DNS issue from the client device, preventing it from reaching the Opsole API endpoints or Microsoft endpoints

Common Cause

Intermittent network or DNS resolution failure on the client device causing the migration process to silently fail without logging to the portal

Resolution

• Check Windows Event Viewer → Applications and Services Logs → OpsoleMigrate and look for any warning or error logs to identify the exact failure point
• Verify the device can reach the Opsole API endpoints and Microsoft endpoints
• Re-run the migration once connectivity is confirmed

Issue 3: Entra Join Failed

Or Entra Join failed screen shows when rebooting after failed Migration

Root Cause

This issue typically occurs when the provisioning package (PPKG) used during the migration is invalid, expired, or configured with incorrect Microsoft Entra credentials. If the bulk enrollment token is expired or the package is not associated correctly with the target tenant, the Entra Join step will fail.

Common Causes

• The provisioning package (PPKG) token has expired
• Incorrect or outdated Entra account credentials were used when generating the PPKG
• PPKG was removed or corrupted by EDR/security software
• Intune/MDM auto-enrollment settings misconfigured
• Token validation failure

Recovery Procedure

1. Verify the Provisioning Package with the current login or reboot and Log in using a local administrator account
2. Open Settings > Accounts > Access work or school > Add or remove a package.
   • if the provisioning package is listed, select it and Remove it.
3. Manually Apply the Provisioning Package
   • Copy the correct Entra provisioning package (PPKG) to the local device.
   • Double-click the PPKG file to begin installation.
   • Select Yes, add it when prompted.
   • The device will apply the provisioning profile.
4. Validate Entra Join Status
   • Run the following command to check join status: dsregcmd /status
   • Confirm the device appears in the Microsoft Entra Admin Portal > Devices and is listed as Entra Joined.
5. Once Entra Join is confirmed, Navigate to: C:\ProgramData\OpsoleMigrate\runtime
6. Run Patch.exe to realign migration state.
7. After patch execution is complete, close the application.
8. Reboot the device.

After reboot, the Opsole Migrate workflow will automatically resume from the point of failure and continue the migration normally.

Issue 4: Migration Window Stuck at "Migration in Process" After Phase 1 Reboot

Root Cause

Phase 2 of the migration did not start because the Task Scheduler failed to launch the InterMigrate activity. This typically occurs when the scheduled task or the executable required for Phase 2 is missing or blocked.

Common Causes

• EDR blocked the creation or execution of the scheduled task
• EDR deleted the scheduled task after creation
• EDR quarantined or removed the InterMigrate executable

When Phase 2 does not run, the device remains stuck on the “Migration in Process” screen after reboot, preventing the user from logging in. A recovery procedure will be required to restore normal access.

Recovery Procedure

Log in using a local administrator account and perform the verification steps below.

Verification Steps

1. Open Task Scheduler and confirm whether the InterMigrate task exists under the Migration folder.
2. Verify that InterMigrate.exe is present in: InterMigrateTask exists

If anything is missing:

• It is likely that your EDR or security software blocked, removed, or quarantined the OpsoleMigrate runtime files or scheduled tasks.
• Review EDR/Antivirus logs to confirm the blocked actions and update your exclusions accordingly.

After confirming that OpsoleMigrate components are properly excluded from EDR/Antivirus scans:

1. Uninstall OpsoleMigrate from Control Panel → Programs and Features
2. Reinstall using OpsoleMigrate.msi
3. Navigate to C:\ProgramData\OpsoleMigrate\runtime
4. Run Patch.exe
5. Once patching is complete, close the application
6. Reboot the device to continue the migration workflow

After reboot, the migration will resume and proceed normally from the point of failure.

Issue 5: Error : User profile is loaded..

Root Cause

The migration process cannot proceed because the user profile being migrated is still loaded or in use after a system reboot. When a profile remains active, Windows prevents Opsole Migrate to executing the profile migration sequence.

This condition is typically caused by background services, scheduled tasks, or applications that continue to run under the affected user’s security context.

Important Note

Thorough pre-migration testing is strongly recommended on representative devices. This helps identify any background processes, services, or applications that automatically start using the user account.

Troubleshooting Steps

1. Review the Opsole Migrate diagnostic results in the portal migration logs. When this issue is detected, Opsole Migrate performs a diagnostic check to help identify processes, services, scheduled tasks, or endpoint tools that may be keeping the user profile or profile-related files in use. Use these log entries to determine what is locking the profile before taking corrective action.

2. Login as local Administrator Run the following in PowerShell (Admin mode):

Get-CimInstance -ClassName Win32_UserProfile | Where-Object { $_.Loaded -eq $True -and $_.Special -eq $False } | Select-Object LocalPath, Loaded, LastUseTime

What you'll see:

LocalPath                        Loaded  LastUseTime
---------                        ------  -----------
C:\Users\domainuser              True    2/21/2026 10:45:00 AM
C:\Users\svc_appservice          True    2/21/2026 9:00:00 AM

Any profile listed here other than the local Administrator is currently loaded in memory will block your migration.

Identify which profile is loaded, investigate the root cause of why that profile is loading, fix the issue, and then continue with the migration.

Recommended Investigation

Identify what is pre‑loading the profile:

• Windows Services running under that user
• Scheduled Tasks set to run as that user (especially At Startup)
• GPO settings that auto-load profiles
• Third-party tools (backup, monitoring, security agents)
• Remote agents caching login sessions
• Check Event Viewer → User Profile Service logs

After identifying the cause , fix the issue. Once the profile is no longer loaded and the system is verified from a local administrator session, the migration can safely resume.

Fix and Resume Migration

1. Log in using a local administrator account
2. Navigate to C:\ProgramData\OpsoleMigrate\runtime
3. Run Patch.exe
4. Once patching is complete, close the application
5. Reboot the device to continue the migration workflow

After reboot, the migration will resume and proceed normally from the point of failure.

Issue 6: Windows Could Not Validate the Entra User Identity

During InterMigrate, the migration may complete with an access permission warning similar to:

• Windows could not validate the Entra user identity.
• Identified AzureAdJoined status is NO. Access permission settings cannot be completed and manual intervention is required.

Root Cause

Windows could not validate or resolve the target Microsoft Entra user identity during access permission configuration.

This can occur when Microsoft Entra identity lookup is unavailable, the device cannot reach Microsoft Entra ID, or the device is no longer Microsoft Entra joined.

Common Causes

• Device is not Microsoft Entra joined
• AzureAdJoined status shows NO
• Microsoft Entra identity lookup is unavailable from the device
• Device was removed from Microsoft Entra ID
• Network or policy restrictions prevent the device from validating the Entra identity

Resolution

• Log in using a local administrator account.
• Open PowerShell as Administrator and verify the device Entra Join status:dsregcmd /status
• If AzureAdJoined shows NO, review the device Entra Join state and identify why the device is not joined.
• Fix the Entra Join issue and join the device to Microsoft Entra ID.
• Contact the support team for manual permission assignment assistance.

Reference For detailed troubleshooting steps, refer to: https://docs.opsole.com/docs/kb#kb-022211

Issue 7: Failed to Unjoin Computer — NTLM Authentication Disabled

Root Cause

• Wrong or expired password for Domain Leave User
• Incorrect username format in portal configuration

Resolution

• Verify domain leave user credentials
• Test manual domain unjoin with same credentials
• Verify domain leave user format in Opsole portal

Issue 8: After Phase 2 Login with Entra ID — Migration Continue Window Does Not Appear

Root Cause

• EDR blocked task
• Application EXE blocked or deleted

Resolution

1. Navigate to:

   C:\ProgramData\OpsoleMigrate\runtime

2. Run postmigration.exe with Admin privileges.
3. If file missing → EDR removed it.
4. Fix EDR issue.
5. Reinstall:

   opsolemigrate.msi

6. Rerun postmigration:

   C:\ProgramData\OpsoleMigrate\runtime\postmigration.exe