Troubleshooting & FAQ

React not loading / blank rect

Symptom: the browser shows as an empty rectangle.

Likely cause: dev server not running; URL wrong; widget URL empty AND DefaultDevURL empty.

Fix: check both URL settings; visit the URL manually in Chrome to confirm it serves your app.

window.ue.bridge is undefined

Symptom: SDK reports the bridge is missing; bridge.send does nothing.

Likely cause: the page was loaded outside UE editor. The bridge only injects under embedded CEF, not in a regular browser.

Fix: use the React SDK's mock/dev mode. UnrealBridgeProvider falls back to a no-op bridge so dev iteration in a real browser works.

Events sent before React is ready

Symptom: state updates from BeginPlay never reach React, or you see EventQueueFull.

Likely cause: events are queued up to MaxEventQueueSize. If you push more than the cap before React mounts, the oldest are dropped.

Fix: raise MaxEventQueueSize in plugin settings, or bind OnReactReady and send on that event.

OnReceived never fires in BP

Symptom: clicking a React button does not trigger the receiver.

Likely cause: EventName mismatch.

Fix: verify EventName matches EXACTLY (case-sensitive). Verify the React side calls bridge.send(eventName, ...) with the same name.

Sender broadcasts when you want a single target

Symptom: every browser receives the push.

Likely cause: TargetBridgeName is empty, which broadcasts.

Fix: set TargetBridgeName on the Sender component to match the browser's BridgeName. Case-sensitive.

HUD doesn't appear on screen

Symptom: the widget is added to the viewport but nothing is visible.

Likely causes, in the order worth checking:

1. The browser's Canvas slot has no size. With Alignment and stretch anchors both left at zero, the slot can collapse to nothing. Select the browser in the Designer and confirm it has a visible rectangle.
2. More than one browser shares a non-Canvas parent. Two ReactWebBrowser widgets under a VerticalBox or Overlay collapse to a single native layer on macOS and only one renders — see Multi-HUD. Make each a direct child of a CanvasPanel.
3. The URL never loaded. A file:// URL pointing into a plugin only resolves in a packaged build if Config/FilterPlugin.ini lists that folder.

Fix: enable Debug Mode in Project Settings — load failures and registration are traced to the Output Log.

Mac UE 5.7 / 5.8 — transparent regions render opaque

Symptom: rgba(0,0,0,.5) and transparent backgrounds render fully opaque.

Likely cause: engine regression on Mac. Confirmed still present on UE 5.8 (PIE-tested 2026-06-25 on UE 5.8.0) — it was hoped fixed in 5.8 but is not.

Fix: see Transparent HUD for workarounds.

Mac UE 5.7 — input doesn't receive keystrokes

Symptom: typing into a React <input> does nothing after opening a chat HUD.

Likely cause: engine regression on Mac UE 5.7 — Slate→CEF keyboard routing is broken. Expected fixed on UE 5.8, but pending PIE verification — keep click-to-type on 5.8 until confirmed.

Fix: click once into the input. See Chat & keyboard focus.

Mac UE 5.7 / 5.8 — white flash on first mount

Symptom: ~100ms of opaque white before React renders.

Likely cause: WKWebView NSView default fill, engine cosmetic issue.

Fix: treat as cosmetic — still present on UE 5.8. See Transparent HUD.

PushMap keys arrive in unexpected order

Symptom: iterating the JS object produces keys in a different order than wired in BP.

Likely cause: BP wire order is non-deterministic.

Fix: read by name on the web side; never rely on iteration order.

Packaged build can't reach localhost:5173

Symptom: dev URL works in PIE but not in Packaged.

Likely cause: dev URL was not swapped for a production URL.

Fix: strip the dev URL. See Production checklist.

FAQ

• Do I have to use React? No. The wire protocol is published at Bridge protocol. Vue, Svelte, vanilla JS all work.
• Which engine versions? UE 5.7+. Windows 64 and Mac.
• Does game logic stay in C++/Blueprint? Yes. State authority stays in UE; React is the view + input layer.
• Production-ready? Yes — the multi-HUD sample is a 4-layer gameplay-bound UI, not a toy.