Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| MFE API calls hang | Bridge not registered | Ensure the host called registerSegmentifyHostApi (dashboard) or bindPostMessageHost / createDirectConfigBridge (partner) before CDP uses the API. |
| Loads but no HTTP / endless skeletons | Duplicate @segmentify/common or React across bundles |
Align shared singletons. The bridge is published on window.SEGMENTIFY_HOST_BRIDGE so federated remotes can find it — a duplicate React/Query instance still breaks it. |
| iframe stays blank | HOST_INIT not sent |
Wait for SEGMENTIFY_MFE_READY before sending init (bindPostMessageHost does this). |
| 401 on API calls | Expired/missing token | Refresh via updateAuthToken() or re-send init with a valid authToken. |
| 500 on API calls (auth OK) | Missing switch headers | Provide requestHeaders with X-Switch-User and X-Switch-Region (match the dashboard Network tab). |
| Switch headers missing in Network tab | Stale @segmentify/common in the MFE |
Rebuild common, pnpm install in the MFE, restart dev:remote. Clear cache: rm -rf node_modules/.pnpm/@segmentify+common*. |
| CORS errors | Partner origin not allowed | Add the domain to the Segmentify API CORS allowlist, or proxy via a partner BFF. |
| CDP wrong API URL in production | Missing dataCenter in host data |
Include dataCenter: 'eq' or 'gc' in hostData. |
| Router sync issues in embed | Expected in embed mode | Host router sync is disabled in embed mode; wire onNavigate to your router instead. |
| Blank screen in Angular federation | React not a shared singleton | Configure react / react-dom as singleton pinned to 18.2.0 in the federation shared config. |
Shared dependency checklist (Module Federation)
Section titled “Shared dependency checklist (Module Federation)”CDP requires these as shared singletons, aligned with its build:
react(18.2),react-dom(18.2)react-intl@tanstack/react-queryreact-hook-form
A version mismatch or a non-singleton React is the most common root cause of blank screens and broken hooks.
Local iframe validation
Section titled “Local iframe validation”Use the partner-sandbox app (see Local setup) to validate
the postMessage contract end to end against dev APIs before shipping.