MigrationFox Agent Troubleshooting

Diagnose and fix issues with the MigrationFox Windows Agent — the on-premises relay used by the SMB connector, the InfoPath PDF Archive, and any Blob Storage migration whose source is SMB.

Where Things Live on Disk

Item	Default path
Agent binary	`C:\MigrationFox\Agent\migrationfox-agent.exe`
Rolling log	`C:\ProgramData\MigrationFox\agent.log`
Windows service name	`MigrationFox Agent`
Local status server	`http://127.0.0.1` on a randomly assigned port logged on startup

Everything the agent writes at runtime goes to C:\ProgramData\MigrationFox\. If you need to hand the agent's state to support, zip that folder. The binary itself is stateless — restoring the binary without the ProgramData folder will re-register the host as a fresh agent.

Reading the Log

The agent writes a single rolling log file:

C:\ProgramData\MigrationFox\agent.log

Tail it live from an Administrator PowerShell:

Get-Content -Path 'C:\ProgramData\MigrationFox\agent.log' -Wait -Tail 200

Each line is a single JSON object with timestamp, level, msg, and operation-specific fields. A healthy startup sequence looks like:

{"level":"info","msg":"agent starting","version":"1.4.2"}
{"level":"info","msg":"registered with control plane","agentId":"agt_01JXYZ..."}
{"level":"info","msg":"poll loop online","intervalMs":5000}
{"level":"info","msg":"status server listening","port":54311}

An unhealthy startup usually has one of these early:

"msg":"token rejected" — the agent token was revoked or never issued to this project. Re-issue from Settings → Agents.
"msg":"control plane unreachable" with a retry count climbing — the machine cannot reach api.migrationfox.com:443. This is a firewall / proxy issue on the host, not a MigrationFox outage 99% of the time.
"msg":"status server port in use" — another process has the configured port. Restart the service and the agent will pick a new port.

Service Management

The agent runs as a Windows service registered by the installer. Standard sc.exe commands apply. Because the service display name contains a space, quote it:

sc query "MigrationFox Agent"
sc start "MigrationFox Agent"
sc stop  "MigrationFox Agent"

Equivalently in PowerShell:

Get-Service -Name 'MigrationFox Agent'
Start-Service -Name 'MigrationFox Agent'
Stop-Service  -Name 'MigrationFox Agent'

Run as console for debugging

To reproduce an issue with full stdout/stderr visible, stop the service and run the binary directly from an Administrator Command Prompt: "C:\MigrationFox\Agent\migrationfox-agent.exe" --token YOUR_TOKEN. You'll see the same JSON lines on stdout in addition to agent.log, and Ctrl+C cleanly shuts it down. Re-start the service when you are done.

Checking & Updating the Agent Version

The running version is logged on every startup ("version":"1.4.2") and is also visible on the Settings → Agents page in the MigrationFox app next to each registered host. Compare against the latest published version on the same page — the "Download Agent" button always serves the current build.

In-place upgrade

From Settings → Agents, click Download Agent and save the new migrationfox-agent.exe somewhere temporary (e.g. C:\Users\admin\Downloads\).
Stop the service:
```
sc stop "MigrationFox Agent"
```
Replace the binary at C:\MigrationFox\Agent\migrationfox-agent.exe with the freshly downloaded one. Keep the same filename — the service registration points at this exact path.
Start the service:
```
sc start "MigrationFox Agent"
```
Tail agent.log and confirm the new version line appears.

Because the agent re-registers with its existing ID on every start, no project-side configuration changes. Any job that was running before the stop will be picked back up by the worker and re-dispatched to the same agent host when it reconnects.

Azure Blob Storage Specific Issues

When the agent is uploading from an SMB source to an Azure Blob destination, the upload path is: SMB file read → in-memory buffer → HTTPS PUT against https://<account>.blob.core.windows.net/<container>/<key> directly from the agent host. The MigrationFox API is never in the data path for the file body. Symptoms of an Azure-specific failure therefore show up almost entirely in the agent log.

HEAD verification

Before the agent starts uploading a batch, it performs a single HEAD against the destination container to confirm reachability and credential validity. This appears in the log as:

{"level":"info","msg":"azure blob preflight","endpoint":"https://contoso.blob.core.windows.net","container":"migrations","status":200}

A non-200 on preflight stops the batch before any upload attempts. The common status codes:

Status	Meaning	Fix
`403`	Credential valid, container access denied — almost always a storage-account firewall.	Add the agent host's public IP to Storage account → Networking → Firewalls and virtual networks, or temporarily switch to Enabled from all networks.
`404`	Container does not exist at the endpoint you're pointed at.	Verify the container name in the credential. If you're on Azure Government / China / Private Endpoint, also verify the explicit `endpoint` value — the default public-cloud hostname will 404 against a sovereign account. See Azure Blob Storage connector.
`409`	Container exists and has an immutability or legal-hold policy in conflict with the write.	Remove the policy for the migration window, or migrate into a new container that has no retention policy applied.
DNS failure / timeout	Hostname does not resolve or is blocked outbound from the agent host.	From the agent machine, run `nslookup <account>.blob.core.windows.net` and `Test-NetConnection -ComputerName <account>.blob.core.windows.net -Port 443`. If either fails, the fix is network-side, not MigrationFox-side.

Expected upload log format

During an active batch the agent writes one line per file on completion:

{"level":"info","msg":"blob uploaded","source":"\\\\fileserver\\shared\\Finance\\Q1.xlsx","blob":"finance/Q1.xlsx","bytes":284716,"elapsedMs":412}
{"level":"info","msg":"blob uploaded","source":"\\\\fileserver\\shared\\Finance\\Q2.xlsx","blob":"finance/Q2.xlsx","bytes":318044,"elapsedMs":389}

And on an individual file failure (non-fatal — the batch continues):

{"level":"error","msg":"blob upload failed","source":"\\\\fileserver\\shared\\HR\\photo.psd","blob":"hr/photo.psd","status":507,"attempts":3}

If uploads appear frozen with no new lines for more than a minute, the first thing to check is Test-NetConnection <account>.blob.core.windows.net -Port 443 from the agent host — intermittent packet loss to the Azure edge is the most common culprit. A service restart clears any stale connection pool:

sc stop  "MigrationFox Agent"
sc start "MigrationFox Agent"

"Files don't appear in the Azure Portal"

If the agent log shows blob uploaded lines but the Azure Portal's blob list is empty, hit the Refresh button inside the container view — the portal does not poll. See the full walk-through including the az storage blob list independent verification on the Azure Blob Storage connector page.

Collecting a Support Bundle

When opening a support ticket for an agent issue, attach the full log and the version/host info. One-liner from an Administrator PowerShell:

$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
$out = "$env:USERPROFILE\Desktop\migrationfox-agent-bundle-$stamp.zip"
Compress-Archive -Path 'C:\ProgramData\MigrationFox\*' -DestinationPath $out
Write-Host "Bundle saved to $out"

The resulting ZIP contains agent.log and the agent's persisted state. Nothing in it is file content from your migration — the agent is stream-through and never writes source data to disk.

SMB / Windows File Shares connector — primary agent use case
Azure Blob Storage connector — frequent destination for SMB migrations
InfoPath PDF Archive — agent-only job type