> ## Documentation Index
> Fetch the complete documentation index at: https://helpdocs.getthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Exchange Hybrid Issues

> Diagnose Exchange hybrid problems — mail stuck between on-prem and Exchange Online, free/busy blank across the boundary, migrations stalled, "user not found" after moves — always starting from which side owns the mailbox.

<Info>
  **Category:** Troubleshooting Playbooks · [View source ↗](https://github.com/bryan-getthread/skills/blob/main/skills/troubleshooting-playbooks/exchange-hybrid-issues/SKILL.md)
</Info>

**Connectors:** `IT Glue` `Hudu`

**Role:** [Technician](/start-here/roles/technician)

**Outcome:** Faster Resolution & Response

**When to use:** Mail flows one direction across the hybrid boundary but not the other (or queues on-prem for the "office 365" send connector); free/busy, calendar sharing, or MailTips are blank between on-prem and cloud users; a mailbox migration is stalled, failed, or "completed" but the user is broken; or after a migration a user can't be mailed ("recipient not found"), can't open shared mailboxes, or shows two mailboxes.

**Run it:** on the one ticket you're working — a tech drives the Exchange shell hands-on with the client's infra owner; not unattended.

## Prompt

```
Every hybrid ticket starts with the same question: which side owns this mailbox? Half of all hybrid "bugs" are a mailbox that lives (or half-lives) on the side nobody thinks it does. General mail-delivery problems without a hybrid boundary belong to the mail-flow-delivery playbook; this one is for the seam itself.

Work it in this order:

1. Version identification first. Check the client's documentation and knowledge base for the hybrid design: on-prem Exchange version/CU, full vs minimal/modern hybrid, centralized mail transport or direct, which connectors HCW built, Entra Connect in the path. An out-of-support CU changes what's advisable — note it. Then establish mailbox ownership for every user in the ticket: on-prem Get-Mailbox vs Get-RemoteMailbox, cloud Get-Mailbox — a user must be exactly one of mailbox-on-prem+MailUser-in-cloud or RemoteMailbox-on-prem+mailbox-in-cloud. Both or neither = your root-cause candidate. Documentation coverage varies per tenant — note anything you could not check.

2. History first. Search this client's past tickets: recent migrations, certificate renewals (hybrid mail flow and OAuth both die on cert expiry — sudden onset on a date is a cert until proven otherwise), HCW runs, firewall changes, and whether this user was recently moved.

3. Get the error before theorizing. Verbatim NDRs (the enhanced status code and the generating server tell you which side rejected), queue viewer state for the hybrid connectors, migration batch/user statistics with the actual error text (Get-MigrationUser | Get-MigrationUserStatistics), and for free/busy the Remote Connectivity Analyzer result — not "free/busy doesn't work". Never invent error codes.

4. Branch:
   - Hybrid mail flow broken (one or both directions) — check in order: certificate validity on the on-prem transport (and that the connector still references the right cert after a renewal), the receive/send connectors HCW created (someone "cleaning up" connectors is a classic), TLS negotiation in the SMTP logs, and whether cloud->on-prem mail is being routed via a changed firewall/NAT. Do not hand-edit HCW-managed connectors (see the HCW rule). Escalate when the fix is firewall/certificate infrastructure owned elsewhere.
   - Free/busy / cross-boundary sharing blank — almost always OAuth or the organization relationship. Test with the user identities involved (direction matters: cloud-seeing-on-prem vs reverse fail differently). Check Test-OAuthConnectivity, the organization relationship / IntraOrganizationConnector state, and whether Autodiscover for the on-prem side still resolves and presents a valid cert externally. Fix by repairing the named broken piece — or by HCW re-run (below) — not by rebuilding sharing objects freehand.
   - Migration stalls/failures — read the per-user statistics, don't watch the percentage. Distinguish: slow (large item counts, throttling — patience, not surgery), stalled with bad items (raise the reality with the client: BadItemLimit is data-loss consent, get explicit sign-off in the ticket before increasing), failed on TooManyLargeItems (items over the size cap will not migrate — the user chooses: export or lose), and stuck at 95% (finalization waiting; often on-prem mailbox lock or content indexing). A completed-but-broken user is usually attribute mismatch — verify targetAddress/ExchangeGuid on the on-prem remote mailbox match the cloud object; pair with entra-connect-sync-errors when the sync layer caused it.
   - "Recipient not found" / two mailboxes / can't open shared mailbox after a move — attribute or ownership drift: missing targetAddress, mail user vs remote mailbox type wrong, or the user was mailbox-enabled on-prem after getting a cloud mailbox (both-sides case — recovery requires deciding which mailbox's content wins; that is a data decision for the client, escalate before touching). Cross-premises shared-mailbox access and some delegation types simply don't work across the boundary — verify against Microsoft's current supportability docs before promising a fix; sometimes the honest answer is "migrate them together".

5. HCW re-run discipline. The Hybrid Configuration Wizard is idempotent for the objects it owns, and re-running it is the supported repair for HCW-managed connectors, org relationships, and OAuth — but treat a re-run as a change: know what it will touch, run it with the same options as the original design (centralized transport toggled differently reroutes the client's mail), and never re-run mid-migration-batch or to "see if it helps" without the client's infra owner aware. Record that it was run and with which selections.

Guardrails to hold throughout: never increase BadItemLimit/LargeItemLimit without the client explicitly acknowledging in the ticket that skipped items are lost. Never hand-edit or delete HCW-created connectors and org relationships; repair via HCW re-run with the correct original options, announced as a change. Never delete either object when a user has both an on-prem and cloud mailbox — which content survives is the client's decision; escalate with the evidence. Do not disable or reroute the hybrid connectors to "get mail moving" — mail that bypasses the boundary loses internal trust properties (headers/attribution) and can create loops; fix the boundary or escalate. Quote NDR codes and migration errors verbatim; verify meanings against Microsoft's current docs on the web (Microsoft Learn) rather than memory — hybrid behavior shifts by CU. If sync (Entra Connect) created the attribute state, fix it at the sync layer — pair with entra-connect-sync-errors, don't hand-edit cloud objects that sync will overwrite. All Exchange shell/console work is guidance for the tech; you never execute it.

Verify and note. Success is the failing artifact passing: a test message each direction with clean headers, free/busy visibly populated both directions, migration user Completed and the user signed in. Leave a plain-text internal note (no markdown, no emojis, raw URLs not markdown links): mailbox ownership findings, verbatim errors/NDR codes, branch, actions (incl. any HCW run + options), verification and time.
```


## Related topics

- [Exchange On-Prem Mail Flow](/skill-library/troubleshooting-playbooks/exchange-onprem-mailflow.md)
- [Co-Managed Reference Exchange](/skill-library/escalation/comanaged-reference-exchange.md)
- [Liongard Exchange On-Prem Read](/skill-library/liongard-inspectors/liongard-exchange-on-prem.md)