Hybrid Configuration Wizard troubleshooting checklist

Symptoms to confirm

• The wizard stops with an error such as Execution of the <cmdlet> cmdlet had thrown an exception and a long stack trace.
• The wizard finishes but lists items that "need to be addressed or potentially configured manually", most often HCW8064: The HCW has completed, but was not able to perform the OAuth portion of your Hybrid configuration.
• It fails before it changes anything: credentials are rejected, it can't connect to your Exchange server, or it reports DataStrings.InvalidSmtpDomainName.
• Hybrid features only half work afterwards: no cross-premises free/busy, or a migration endpoint that won't validate.

Likely causes

• The HCW is a client application that opens PowerShell sessions to your Exchange organization and to Exchange Online and runs a long sequence of cmdlets: it saves your choices in the HybridConfiguration object in Active Directory, proves domain ownership for the federation trust, sets up the organization relationship and OAuth, configures connectors on both sides and creates the migration endpoint.
• Each task depends on something outside the wizard: TLS 1.2 and internet access, permissions, clean Active Directory data, Autodiscover and EWS published to the internet, and a valid public certificate.
• The wizard shows only the last exception; the log shows which task, cmdlet and side failed.

Checklist

1. 1

   Rule out the basics

   • Always download the current wizard from https://aka.ms/hybridwizard; don't reuse an old copy.
   • Run it on an up-to-date Exchange Server Subscription Edition (SE) server. Exchange 2016 and 2019 reached end of support on 14 October 2025, so a hybrid server should be on SE.
   • Use an on-premises account in the Organization Management role group, and a Microsoft 365 admin account with the roles the wizard needs. Microsoft's HCW overview lists the role required for each feature; Global Administrator covers them all.
   • Make sure the server can reach Microsoft 365 over HTTPS without SSL inspection breaking the connection.
2. 2

   Open the log and find the first error

   By default the log is written to %AppData%\Microsoft\Exchange Hybrid Configuration in the profile of the user who ran the wizard, on the machine where it ran. The newest file is your last run:

   powershell

   $dir = Join-Path $env:APPDATA 'Microsoft\Exchange Hybrid Configuration'
   $log = Get-ChildItem $dir -Filter *.log -Recurse | Sort-Object LastWriteTime -Descending | Select-Object -First 1
   Select-String -Path $log.FullName -Pattern 'ERROR' -Context 0,2 | Select-Object -First 3

   A typical entry looks like this (shortened):

   <timestamp> ERROR 10277 [Client=UX, Activity=Domain Ownership, Session=OnPremises,
   Cmdlet=Set-FederatedOrganizationIdentifier, Thread=6] FINISH Time=1075.1ms
   Results=PowerShell failed to invoke 'Set-FederatedOrganizationIdentifier': ...
   "The underlying connection was closed: An unexpected error occurred on a send."

3. 3

   Match the failure to its fix

   What the log shows	Usual cause	Fix
   "The underlying connection was closed" during federation, OAuth or connection steps	.NET Framework on the server isn't using TLS 1.2, or a proxy is interfering	Set the .NET TLS registry values below, restart, run the wizard again
   DataStrings.InvalidSmtpDomainName	A decommissioned Exchange server is still in Active Directory and Get-ExchangeServer still lists it	Remove the stale server object as described in Microsoft's article for this error, wait for AD replication, then run the wizard again
   Get-FederationInformation or organization relationship tasks fail	Your domain's Autodiscover endpoint isn't reachable from the internet, has an untrusted certificate, or sits behind pre-authentication	Publish autodiscover.contoso.com to the hybrid servers and test it with the Microsoft Remote Connectivity Analyzer (testconnectivity.microsoft.com)
   Send connector, receive connector or inbound connector cmdlets fail	The chosen certificate is missing (or has no private key) on one of the selected servers, isn't enabled for SMTP, or isn't from a public CA	Import and enable the certificate on every selected transport server, then run the wizard again
   HCW8064 at the end	OAuth configuration hit a transient or permanent error: TLS, an expired Exchange Server Auth Certificate, or connectivity	Run the wizard again; if it persists, fix the cause and follow Microsoft's manual OAuth steps
   Migration endpoint task fails	MRS Proxy disabled, or EWS not published or pre-authenticated	Enable MRS Proxy and test the endpoint (see below)

   For TLS, these values make .NET Framework use the operating system's TLS defaults, which include TLS 1.2:

   powershell

   $paths = 'HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319',
            'HKLM:\SOFTWARE\WOW6432Node\Microsoft\.NETFramework\v4.0.30319'
   foreach ($p in $paths) {
     New-ItemProperty -Path $p -Name SystemDefaultTlsVersions -Value 1 -PropertyType DWord -Force
     New-ItemProperty -Path $p -Name SchUseStrongCrypto -Value 1 -PropertyType DWord -Force
   }

   For HCW8064, check the Auth Certificate before anything else:

   powershell

   Get-ExchangeCertificate -Thumbprint (Get-AuthConfig).CurrentCertificateThumbprint |
     Format-List Subject, NotAfter, Status

   For the migration endpoint, enable MRS Proxy on every server that publishes EWS, then test from Exchange Online PowerShell:

   powershell

   Set-WebServicesVirtualDirectory -Identity "EX01\EWS (Default Web Site)" -MRSProxyEnabled $true
   # Exchange Online PowerShell
   Test-MigrationServerAvailability -ExchangeRemoteMove -RemoteServer mail.contoso.com -Credentials (Get-Credential)

   Watch out: If you have moved hybrid OAuth to the dedicated Exchange hybrid application, a wizard run that includes the OAuth step can put the Auth Certificate back on the shared Exchange Online service principal. Afterwards, run the dedicated-app script's service principal clean-up again, as described in my hybrid free/busy article.

4. 4

   Run the wizard again

   Running the wizard again is the normal way to finish or repair a hybrid configuration. By default it enables every hybrid feature on each run, so repeat your previous choices unless you mean to change them.

Verify

• The wizard ends without errors or "configure manually" items.
• The stored configuration matches your intent:
  powershell

  Get-HybridConfiguration | Format-List Domains, Features, SendingTransportServers,
    ReceivingTransportServers, TlsCertificateName

• In Exchange Online PowerShell, Get-InboundConnector, Get-OutboundConnector, Get-IntraOrganizationConnector and Get-MigrationEndpoint return the objects the wizard created.
• Mail flows both ways between an on-premises and a cloud mailbox, free/busy works in both directions, and Test-MigrationServerAvailability returns Success. For migration batches, see Hybrid mailbox migration batches.

Prevent it next time

• Keep hybrid servers on the latest Exchange SE update.
• Write down your choices (servers, certificate, FQDN, features) and keep the log from a successful run as a baseline.
• Track the expiry of both the transport certificate and the Auth Certificate; see Renewing the Exchange hybrid certificate.
• Decommission Exchange servers by uninstalling them, not by switching them off, so they don't linger in Active Directory.
• Test Autodiscover and EWS from the internet before you run the wizard, not after.