Migration Agent is not starting or registering on a device
Learn how to troubleshoot why the Migration Agent is not launching properly on your device and potential solutions to fix the issue.
Written by Neil Langston
Updated at March 18th, 2026
Table of Contents
Event viewer & agent reporting
Application Event viewer is your friend here, look for any errors, problems are likely to be there on the device.
Within the server navigation in Migration Agent, use the reports section to review where there might be problems
- “Agents”: Is the device registered
- “Agent logs”: see granular information on the progress of the device, most events will appear here.
- “Failed communication”: for any other telemetry errors.
Internet access or access to the PowerSyncPro server from the device.
Whilst the Migration Agent on the device downloads the runbooks in advance in preparation for your migration event, the Migration Agent queries the server over the internet under three conditions:
- When the computer starts or the PowerSyncPro Migration Agent service is restarted.
- Every hour since the last time the PowerSyncPro Migration Agent was started (or the polling interval you have specified on the migration agent install)
- If you use the tray application to check for runbooks or start a migration.
and most importantly.
- At the time when the runbook is due to run, or immediately if that is in the past, PowerSyncPro Migration Agent verifies with the server the device is still in scope before running.
- Throughout the migration to upload logs, and receive any additional translations required.
If you have only just assigned the machine to a runbook, then you will need to restart the PowerSyncPro Migration Agent service on the device for immediate migration. Alternatively, the user can use the tray application to check for runbooks, or the Migration Agent will communicate with the server within 1 hour.
Certificate on the device.
Navigate to the PSP server from the browser on your device ensure you're able to reach the site and there are no certificate problems with the website. You will need to be able to access to access the PowerSyncPro server throughout the migration of the workstation, so ensure you are able to do this even during device state changes, where an interim state might be WORKGROUP joined.
The here is an example endpoint you may be using:
UTC Time or local time of batch.
Verify the time on the appropriate batch is correct for the device time.
Device not assigned to a batch
A machine will only start the migration if it has been correctly assigned to a batch.
If you think it has been assigned correctly check event viewer on the device to see if runbooks have been received.
Furthermore, the Migration Agent checks the server every hour, so you many want to restart the service to force it to start.
Runbook has already completed on the device.
If you want all runbooks to re-run on a device once more, you will need to delete them from the ProgramData folder on the device.
You will find the runbook IDs here
C:\ProgramData\Declaration Software\Migration Agent
Once you have deleted the runbook(s), restart the agent service so it will immediate retrieve the in scope runbooks once more. Clicking “check runbooks” in the task bar may not be sufficient if Migration Agent is holding knowledge of runbooks in the memory.
Ensure the device has registered
On the PowerSyncPro server, navigate to Migration agent > Agents, and search for the device.
If the device isn't registered on the server, on the device check the agent is installed and if there are any errors in event viewer.
You can also look at “Fail Communications” to see any error messages related to the device.
Only imported devices into PSP server will register, so ensure the correct directory is being imported, and a import has run recently, or the schedule is active.
Licensing
If you are not licensed for the domain that the machine is on. Check event viewer on the workstation.
Contact the sales team where you purchased your licenses..
PreSharedKey (PSK) and Server URL
Sometimes the wrong PSK or Server URL is entered into the installation GUI or command line of the PowerSyncPro Migration Agent installation. You should check the event viewer to see if there are any issues reported by PowerSyncPro on the device.
The server URL is typically something like the following fictional servers depending on your setup.
Silent Runbook or dependencies not complete
Sometimes the runbook may have been chosen to be silent, or the dependencies have not completed.
In the case of offline domain join, the user may not have entered their credentials, you you may have to wait until the prompt appears again.
User has utilised the grace period option.
It is possible the user had delayed their migration when they received the popup, which is configurable in the batch. Check event viewer. If you are past the enforce after time, then there is still a grace period of 1 hour where the user will be prompted every 15mins before the migration is forced upon them.
Servers excluded
If you're migrating a server, check the runbook is enabled for servers.
The Migration Agent is running long operations
Some machines may have a considerable amount of data, therefore updating permissions could take a very long time. We've seen this on non-SSD machines, and especially servers with large amounts of file data.
Furthermore, at a kiosk or shared machines, if there are lots of user profiles, there is a considerable amount of time required to go through all those and perform repermissioning.
Missing Domain.Read.All permission in Entra ID
Please check the Source Entra Directory name in PSP.
If it displays the Tenant ID instead of the default *.onmicrosoft.com domain name, it indicates that the Domain.Read.All permission is missing from the App Registration in Entra ID.
To resolve this issue:
Add the Domain.Read.All permission to the App Registration.
Grant Admin Consent for the permission.
Recreate the directory in PSP.
If the project has already been configured and you want to avoid deleting the directory and all related components, please contact PSP Support to regenerate the license.