Azure Virtual Desktop Hybrid

This article helps administrators and support personnel triage Azure Virtual Desktop session host onboarding failures on Azure Arc-enabled and Azure virtual machine (VM) environments. Use it to identify which phase of the Enable command failed, what the failure means, and how to recover.

How to read this article

The Enable command runs through six sequential phases. A failure in any phase stops the flow, except for background checks. Each row in the tables below shows the following information.

Column Meaning
Error message (in logs) The exact text you find in the extension log.
HTTP status 400 indicates a customer-recoverable error. 500 indicates a system or security error.
Root cause What triggered the failure.
Recovery action What you should do to resolve the issue.
Docs A link to official Microsoft documentation.

Log locations

  • Extension handler log: C:\ProgramData\GuestConfig\extension_logs\Microsoft.AzureVirtualDesktop.CloudDeviceExtension\
  • Windows event log: Application log (source: msiexec)

Key log patterns to search for

Search for the following patterns in the extension log to find the most relevant entries:

[Fatal]:       The final error that caused the Enable to fail.
[Error]:       Nonfatal errors. These errors might have been retried or fallen back.
[Warn]:        Warnings. The extension is degraded but continuing.
status.*error  Status reports sent to Azure Resource Manager (visible in the Azure portal).

Phase 0: Extension install (OnInstall)

This phase enables Remote Desktop Protocol (RDP). On Windows Server, the Remote Desktop Session Host (RDSH) role is installed. On Windows 11, RDP is enabled.

# Error message (in logs) HTTP Root cause Recovery action Docs
0.1 RegistryKeyDoesNotExistException: The registry Key SYSTEM\CurrentControlSet\Control\Terminal Server does not exist 500 The Terminal Services component is missing or corrupted. Verify that the Windows Server installation isn't corrupted. Run sfc /scannow. Ensure the Remote Desktop Services role is available. Install Remote Desktop Services roles
0.2 RegistryKeyDoesNotExistException (writing fDenyTSConnections) 500 There are insufficient permissions to write to the Terminal Server registry. Run the extension with SYSTEM-level privileges. Check for Group Policy overrides on fDenyTSConnections. —

Phase 1: Environment detection and proxy validation

The extension detects whether it's running on an Azure VM (using the Azure Instance Metadata Service (IMDS) at 169.254.169.254) or on an Azure Arc-enabled server (using the Hybrid Instance Metadata Service (HIMDS)). The extension also validates the proxy configuration.

# Error message (in logs) HTTP Root cause Recovery action Docs
1.1 Metadata endpoint http://169.254.169.254/... failed ... Assuming it's not present. — This message isn't an error. IMDS is unreachable on Azure Arc machines, which is expected. The extension falls back to HIMDS detection. No action is needed. This behavior is normal on Azure Arc-enabled servers. —
1.2 Invalid proxy detected from {source}. URL: {rawUrl} followed by The extension cannot make outbound HTTP calls until this is corrected. 400 The proxy URL in the Azure Arc agent configuration or in environment variables is malformed. For example, the URL is missing a scheme or contains invalid characters. Fix the proxy URL in the Azure Arc agent configuration at C:\ProgramData\AzureConnectedMachineAgent\Config\agentconfig.json, or in the HTTPS_PROXY or HTTP_PROXY environment variables. Restart the extension. Configure a proxy for Azure Arc
1.3 Arc config file is missing proxy settings. — This message is informational only. No proxy is configured in the Azure Arc agent configuration. The extension proceeds without a proxy. No action is needed unless the VM requires a proxy to reach Azure endpoints. —

Phase 2: Configuration and token validation

The extension loads settings, validates the registration token (a JSON Web Token, or JWT), and checks tenant alignment.

# Error message (in logs) HTTP Root cause Recovery action Docs
2.1 Already applied configuration change with a higher sequence number. Specified sequence number is '{n}', last applied is '{n}'. — This message is a warning only. The same configuration is already applied. The extension continues to evaluate whether a retry is needed. No action is needed. This behavior is normal during reenables. —
2.2 Protected settings must be passed to OnEnable - verify ARM template configuration 400 The Azure Resource Manager (ARM) deployment didn't include protectedSettings containing the registration token. Redeploy the extension with a valid ARM template that includes protectedSettings.RegistrationToken. Verify that the ARM template has both a publicSettings section and a protectedSettings section. Add session hosts to a host pool
2.3 The provided registration token is not valid 400 The registration token is malformed. It isn't a valid JWT or can't be parsed. Generate a new registration token. Redeploy the extension with the new token. Generate a registration key
2.4 The provided registration token is expired - cannot proceed with registration to host pool 400 The JWT token's exp claim is in the past. Generate a new registration token. Set an appropriate expiration of up to 27 days. Redeploy the extension with the new token. Generate a registration key
2.5 Tenant validation failed: registration token tenant '{tokenTenantId}' does not match machine tenant '{machineTenantId}'. Cross-tenant registration is not permitted. 500 The Azure Arc-connected machine belongs to a different Microsoft Entra tenant than the host pool's registration token. Ensure that the Azure Arc machine is onboarded to the same Microsoft Entra tenant as the Azure Virtual Desktop host pool. Either reonboard the Azure Arc machine to the correct tenant, or use a registration token from a host pool in the machine's tenant. Azure Arc prerequisites
2.6 Arc-enabled server but machine tenant could not be determined from Arc agent configuration. Cannot verify tenant — blocking registration. 500 The Azure Arc agent configuration file at %PROGRAMDATA%\AzureConnectedMachineAgent\Config\agentconfig.json is missing or doesn't contain a tenant ID. Verify that the Azure Arc agent is properly connected. Run azcmagent show and check the Tenant ID field. If the field is empty, reconnect the machine to Azure Arc. Troubleshoot Azure Arc agent onboarding
2.7 Registration token is missing the required 'AADTenantId' claim. 500 The registration token JWT doesn't contain an AADTenantId claim. This behavior is unusual and might indicate a very old or corrupted token. Regenerate the registration token. If the issue persists, contact Microsoft Support. The host pool might have a configuration issue. Generate a registration key

Phase 3: MSI download and installation

The extension downloads the Remote Desktop Agent (RDAgent) and RDAgentBootLoader MSIs from the Azure Virtual Desktop broker, validates their Authenticode signatures, and installs them by using msiexec.

3A: Broker connectivity

# Error message (in logs) HTTP Root cause Recovery action Docs
3.1 Unable to reach the broker 500 The broker endpoints are unreachable. A DNS failure, a firewall that is blocking traffic, or a network outage might cause this issue. Check network connectivity to the Azure Virtual Desktop broker endpoints. Ensure that the VM can reach *.wvd.azure.cn on port 443. Check firewall rules, network security groups (NSGs), and proxy settings. Required URLs for Azure Virtual Desktop
3.2 Call to broker uri {uri} failed or Broker health endpoint ping for {uri} failed 500 The broker API returned an error such as 403 Forbidden, 500 Internal Server Error, or 503 Service Unavailable, or the connection timed out. Verify that the registration token is valid and not expired. Check for an Azure service outage on the Azure Status page. Retry the deployment after a few minutes. Azure Service Health
3.3 Request to get the agent download uri failed 500 The broker responded but returned an unexpected response or a missing MSI download URL. This issue is likely transient on the broker side. Retry the extension deployment. If the issue persists, check the Azure Status page for Azure Virtual Desktop service issues. —

3B: MSI signature validation

# Error message (in logs) HTTP Root cause Recovery action Docs
3.4 Authenticode signature validation failed for '{fileName}': signed by unexpected publisher '{name}', expected 'Microsoft Corporation' 500 The downloaded MSI was signed by the wrong publisher. This behavior might indicate a machine-in-the-middle attack, proxy tampering, or content delivery network (CDN) corruption. The extension falls back to the backup MSI. Check whether a TLS-inspecting proxy is rewriting the downloaded binaries. Ensure that no security appliance modifies HTTPS traffic to *.wvd.azure.cn. Add the Azure Virtual Desktop URLs to the proxy bypass list. Required URLs for Azure Virtual Desktop
3.5 Authenticode signature validation failed for '{fileName}': file does not exist 500 The download appeared to succeed, but the file is missing on disk. A disk issue or antivirus quarantine might cause this issue. The extension falls back to the backup MSI. Check whether antivirus software quarantined the file. Verify that the C:\DeployAgent\ directory is writable and has sufficient disk space. Add the Azure Virtual Desktop extension paths to the antivirus exclusions. —
3.6 Downloaded MSI failed signature validation, falling back to backup. — This message is a warning only. Signature validation failed on the downloaded MSI, but the extension is trying the locally cached backup copy. If the backup succeeds, no action is needed. If the backup also fails, see the guidance in row 3.4. —

3C: MSI installation (msiexec)

The extension runs msiexec.exe /i {msi} /quiet /qn /norestart.

# Error message (in logs) Exit code HTTP Root cause Recovery action Docs
3.7 MSI installation failed with exit code 1601 1601 400 The Windows Installer service is disabled or misconfigured. Open services.msc and ensure that the Windows Installer service is set to Manual rather than Disabled. Run msiexec /regserver to reregister the service. Windows Installer error codes
3.8 MSI installation failed with exit code 1602 1602 400 The installation was canceled. This outcome is unlikely in silent mode and might indicate that Group Policy is blocking MSI installations. Check Group Policy at Computer Configuration > Administrative Templates > Windows Components > Windows Installer. Ensure that Disable Windows Installer isn't enabled. Windows Installer error codes
3.9 MSI installation failed with exit code 1610 1610 400 Product configuration data is corrupted in the Windows Installer database. Run sfc /scannow and DISM /Online /Cleanup-Image /RestoreHealth. If a previous Azure Virtual Desktop agent installation is corrupted, manually uninstall it from Programs and Features, and then retry. Windows Installer error codes
3.10 MSI installation failed with exit code 1612 1612 400 The installation source (the MSI file) is unavailable. The operation is retried automatically. Check the disk space on C:\DeployAgent\. Ensure that there are no file locks. If retries and the backup all fail, check for disk I/O errors in Event Viewer. Windows Installer error codes
3.11 MSI installation failed with exit code 1618 1618 400 Another MSI installation is already running. The operation is retried automatically with backoff. Wait for other MSI installations to finish. Run tasklist /fi "imagename eq msiexec.exe" to confirm. If a process is stuck, investigate and end the blocking msiexec process, and then retry. Windows Installer error codes
3.12 MSI installation failed with exit code 1603 1603 500 A generic MSI installation failure occurred. Check C:\DeployAgent\rdagent.txt for a detailed MSI log. Review the MSI log at C:\DeployAgent\rdagent.txt or C:\DeployAgent\bootloader.txt. Common causes include insufficient disk space, a file in use, or corrupted Windows components. Run sfc /scannow. Windows Installer error codes
3.13 Terminating MSI runner! (the process is killed after timeout) — 500 msiexec hung for more than five minutes. A disk I/O hang, a deadlock, or resource contention might cause this issue. Check for disk errors, high CPU or memory usage, or Group Policy scripts that interfere with the installation. Restart the VM and retry. —

Phase 4: Attachment validation pipeline

After the MSI installation succeeds, the extension runs a five-step validation pipeline to confirm that the session host is fully operational. The pipeline has a 20-minute total timeout.

# Timeout Error message (in logs) HTTP Root cause Recovery action Docs
4.1 5 min Failed to start bootloader service 500 The RDAgentBootLoader Windows service failed to start after the MSI installation. Check the Windows event log (Application and System) for service start failures. Verify that the service executable exists. Run sc query RDAgentBootLoader. Try manually starting the service by running net start RDAgentBootLoader. Troubleshoot the Azure Virtual Desktop agent
4.2 120 s Broker did not accept registration within allocated interval 400 The agent couldn't register with the Azure Virtual Desktop broker within two minutes. A network issue, a token problem, or broker rejection might cause this issue. Check network connectivity to *.wvd.azure.cn:443. Verify that the registration token is valid. Check the RDAgent service logs at C:\Program Files\Microsoft RDInfra\AgentInstall.txt. Troubleshoot the Azure Virtual Desktop agent
4.3 — Bootloader service stopped unexpectedly during registration, with event log details such as NAME_ALREADY_REGISTERED 400 The RDAgent service stopped during registration. The event log entry reveals the broker's rejection reason, for example, a VM name conflict. For NAME_ALREADY_REGISTERED, another session host with the same VM name already exists in the host pool. Remove the stale entry from the host pool, and then retry. For other broker errors, check the detailed event log message.
4.4 600 s SxS provisioning still in progress 400 Side-by-Side (SxS) stack provisioning for the Remote Desktop components didn't finish within 10 minutes. Check the RDAgent service logs. Verify that the SxS stack MSI installed correctly. A common fix is to restart the RDAgent service and wait for SxS provisioning to finish. Troubleshoot the Azure Virtual Desktop agent
4.5 — SxS stack provisioning failed, with an ExecutionActionMessage value from the registry 400 SxS stack provisioning explicitly failed. The registry contains the specific error message. Read the ExecutionActionMessage value at HKLM\SOFTWARE\Microsoft\RDInfraAgent\AVDAgentProvisioning\AVDStackProvisioningService for the specific failure. Common causes include port conflicts or missing Windows features. Troubleshoot the Azure Virtual Desktop agent
4.6 600 s WebSocket was not established within allotted time, inspect your VM 400 The RDAgent didn't establish a WebSocket connection to the broker within 10 minutes. Verify outbound connectivity to *.wvd.azure.cn:443. Check that firewall rules and NSGs allow WebSocket upgrades from HTTP/1.1 to WebSocket. Verify that TLS-inspecting proxies aren't breaking WebSocket handshakes. Required URLs for Azure Virtual Desktop
4.7 — Provisioning failed ({service}) — This message is background-only and informational. It doesn't block the Enable result. It's logged as a warning. Monitor the RDAgent logs. Provisioning failures here are typically transient and self-resolve on subsequent agent heartbeats. —

Phase 5: General and catch-all errors

The following errors apply when an unhandled exception occurs during the Enable flow.

# Error message (in logs) HTTP Root cause Recovery action Docs
5.1 An internal error occurred. Check extension logs for details. 500 An unhandled exception occurred. The actual error is in the extension log, prefixed with [Fatal]:. Collect the full extension log and look for the [Fatal]: line. Provide the log to Microsoft Support if the error isn't self-explanatory. Collect Azure Virtual Desktop agent logs
5.2 Any [Fatal]: message with a specific user-facing error 400 A known recoverable error occurred. The message itself describes the issue. Follow the guidance in the error message. Cross-reference the guidance with the specific rows in the preceding tables. —

Next steps

  • Last updated on