Exchange Hybrid Configuration Wizard: Setup and What Breaks

The Hybrid Configuration Wizard, usually just HCW, is a small download that makes a lot of changes on both sides of your Exchange organization. When it works it feels like magic. When it fails, the error text is often a symptom two steps away from the real cause.

This post covers what you need before you run it, what it configures, and the failures we see most often on real servers.

Before you run the wizard

The wizard assumes a healthy Exchange organization that the internet can reach. Most failures trace back to one of these items not being true.

Run it from an Exchange server, or from a domain-joined machine with the management tools, logged on as an account that is an Organization Management member on-prem and a Global Administrator in the tenant.

Exchange on a supported cumulative update. The wizard checks this and refuses old builds.
Entra Connect installed and completing a sync cycle with the Exchange hybrid writeback option enabled.
The public domain added and verified in the tenant, and the tenant's routing domain, usually contoso.mail.onmicrosoft.com, added as an accepted domain on-prem by the wizard.
A third-party certificate on Exchange that covers mail.domain.com and autodiscover.domain.com, assigned to IIS and SMTP.
Port 443 open inbound from the internet to Exchange for EWS and Autodiscover, and port 25 in both directions for the mail flow connectors.
Autodiscover DNS pointing at the on-prem server, not at Exchange Online yet.
The MRS proxy enabled on the EWS virtual directory.

Get-WebServicesVirtualDirectory | Set-WebServicesVirtualDirectory -MRSProxyEnabled $true
Get-ExchangeCertificate | Where-Object { $_.Services -like "*IIS*" } | Select Thumbprint, Subject, NotAfter, CertificateDomains
Test-OutlookWebServices -Identity user@domain.com | Format-Table Scenario, Result

What the wizard actually changes

It helps to know what HCW does so you can check each piece by hand if a later step misbehaves. On-prem it creates a federation trust with the Microsoft federation gateway, an organization relationship pointed at the tenant, a send connector to Exchange Online, a receive connector for Microsoft's IP ranges, and it adds the tenant routing domain to the email address policies so every mailbox gets a user@contoso.mail.onmicrosoft.com address.

In the tenant it creates an inbound and an outbound connector for your public IPs or certificate, an organization relationship back to you, and the migration endpoint. It also enables OAuth between the two organizations, which is what makes free/busy and mailbox moves authenticate without passwords.

The whole configuration is stored on-prem in the HybridConfiguration object and can be read back.

Get-HybridConfiguration | Format-List
Get-OrganizationRelationship | Format-List Name, DomainNames, FreeBusyAccessEnabled, TargetAutodiscoverEpr
Get-SendConnector "Outbound to Office 365*" | Format-List Name, AddressSpaces, TlsDomain, SmartHosts
Get-IntraOrganizationConnector

Full, minimal or agent-based

The wizard asks which flavor you want. Full hybrid includes sharing of free/busy and calendar details across both sides. Minimal hybrid leaves those out and is fine if every mailbox will move within a few weeks. The Hybrid Agent option installs a small service that connects outbound to Azure and publishes EWS and Autodiscover through it, so inbound port 443 to Exchange is not needed for moves and free/busy. Mail flow still requires port 25 and the connectors in both cases.

Choose classic full hybrid if the network side is already done and you may run coexistence for a while. Choose the agent if opening an inbound port is a hard no. Do not mix them: switching later means re-running the wizard and cleaning up the old endpoint.

The failures we see most

The wizard writes detailed logs to the running user's profile, and reading the last few hundred lines is faster than guessing.

Certificate not trusted or not assigned: the wizard cannot find a valid third-party certificate for the connectors. Assign it to SMTP with Enable-ExchangeCertificate and confirm the subject matches the hostname you enter for mail flow.
Autodiscover points somewhere else: if autodiscover.domain.com resolves to a web host or a CNAME to Exchange Online, federation and free/busy fail. Fix DNS first.
Microsoft's ranges blocked at the firewall: mail flow tests time out. Allow the published Exchange Online IP ranges on 25 and 443, and check for a SonicWall or similar device doing SMTP inspection that strips STARTTLS.
MRS proxy disabled or an IIS reset needed: moves fail with an endpoint error even though the wizard finished. Enable it and restart IIS.
Entra Connect not in Exchange hybrid mode: cloud objects lack the on-prem mailbox GUID and moves fail with a mailbox already exists error. Re-run the Connect wizard, tick the hybrid option, run a full sync.
Expired federation metadata or a stale trust from an earlier attempt: remove the federation trust and organization relationship and let the wizard recreate them.

Get-ChildItem "$env:APPDATA\Microsoft\Exchange Hybrid Configuration" | Sort LastWriteTime -Descending | Select -First 3
Test-MigrationServerAvailability -ExchangeRemoteMove -RemoteServer mail.domain.com -Credentials (Get-Credential)
Test-FederationTrust -UserIdentity user@domain.com

Verifying before the first move

Do not start a production batch until three things work. First, a test mailbox move of a small account completes and the user can open Outlook. Second, free/busy shows in both directions between a moved user and an on-prem user. Third, an internal message from on-prem to the moved mailbox arrives with the internal header intact, which you can check in the message trace by looking for the hybrid connector name.

If any of these fails, fix it while it affects one person, not a department.

Frequently asked questions

Do I need an Exchange license for the hybrid server?

If the server hosts no mailboxes and exists only for hybrid management and coexistence, Microsoft provides a hybrid product key through the wizard. Check the current terms in the wizard itself, since they have changed over versions.

Can I run HCW more than once?

Yes, and you will. It is safe to re-run after changing certificates, adding domains, or switching between full and minimal. It updates the existing configuration rather than duplicating it.

Where are the HCW logs?

Under the profile of the account that ran it, in AppData\Roaming\Microsoft\Exchange Hybrid Configuration. Each run creates a timestamped log with the exact cmdlets executed on both sides.

Takeaway

The wizard is reliable when the prerequisites are real: a trusted certificate, correct Autodiscover, open ports, hybrid-mode directory sync and MRS proxy on. Almost every failure is one of those five. Check them before you start, read the log when it stops, and prove the setup with one mailbox before you trust it with a department.