Troubleshooting HCP Unreal
The WebSocket drops and capture seems to stop
Cause. Check the Output Log for LogHEATCapture first - as of this version, a dropped
connection reconnects automatically with backoff (see
Interface control document), so this usually means either the retry is
still in progress (look for repeated log lines with an increasing delay, capped at
RetryMaxDelaySeconds), or HEAT Capture genuinely never became reachable again during the
level’s lifetime.
Fix. If retries are visibly happening, this is expected behaviour during an outage - frames
built in the meantime are buffered (bounded by MaxBufferedFrames/MaxBufferedMegabytes) and
sent once reconnected, not lost, unless the outage outlasts the buffer. If no retry attempts are
logged at all, confirm StartSession() was actually called - the supervisor loop that retries
only runs between a StartSession() and the matching StopSession().
A changed ServerHostname/ServerPort (or any reliability setting) doesn’t seem to apply
Cause. These are read once, when the level starts, and baked into the running connection -
see Configure. Only UpdateRate is read fresh every tick.
Fix. Restart the level (or the editor) after saving the setting.
An AHEATActor registers successfully but never produces position data
Cause. AHEATActor’s own registration path (RegisterEntity) does not synthesize a
transform automatically. See Data produced.
Fix. Attach a HEATTransformComponent to the actor.
Session start keeps failing with “no user is signed in”
Cause. /api/session/* requires a signed-in user in HEAT Capture; the plugin recognises a
401 response specifically and logs it this way rather than a generic failure.
Fix. Sign in to HEAT Capture. No restart of the Unreal side is needed - the retry loop picks up the newly-available session on its next attempt.
Session start keeps failing for another reason
Cause. Every attempt is logged with the specific cause: an HTTP status code from HEAT Capture, or “could not reach HEAT Capture” for a connectivity failure. This repeats indefinitely with backoff rather than giving up.
Fix. Confirm HEAT Capture is running and reachable at the configured host and port.
ServerPort defaults to 5005, matching HEAT Capture’s own default, so a mismatch usually means
one side’s port was changed without the other.
A capture component’s data is always the default/zero value
Cause. Nothing is populating it. Direct properties on the component default to zero/false
and stay there unless something sets them - a CaptureConfig binding, an OnProvideData bound
event, or your own code setting the UPROPERTY values directly.
Fix. See Data binding for the three binding methods and their precedence.
Events never appear even though EmitTrackingEvent/EmitJsonDataEvent is being called
Cause. Either rate limiting is silently dropping them (bEnableRateLimit on with a low
MaxEventsPerSecond), or the emitting component’s owner actor was never registered as an entity
- events are attributed by entity id, and an unregistered actor has none. Also check
bCaptureEnabled/bEnableEventEmissionhaven’t been turned off on the component.
Fix. Confirm the owning actor is registered, and check whether rate limiting is enabled before assuming the event itself is broken.