Troubleshooting & FAQ

React not loading / blank rect

Symptom: the HUD layer 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 HUD layer receives the push.

Likely cause: TargetBridgeName is empty, which broadcasts.

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

HUD doesn't appear on screen

Symptom: Add Web HUD returns an invalid handle or nothing renders.

Likely cause: called before viewport existed (called outside BeginPlay?), or Size is out of range.

Fix: call from BeginPlay or later. Verify Size is between 0 and 1 on both axes.

Mac UE 5.7 — transparent regions render black

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

Likely cause: engine regression on Mac UE 5.7.

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.

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

Mac UE 5.7 — 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 until 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.