Develop

Movement SDK troubleshooting

Updated: Apr 15, 2026

After completing this section, you should:

Understand the steps to troubleshoot issues.

Understand how to use visualization tools to debug retargeting.

General troubleshooting

First, verify that you have set up general configuration settings correctly. Follow these steps to verify the configs:

Review the steps outlined in Unreal Project Setup.

If you haven’t resolved the problem by checking the configuration steps above, use the following guidelines to isolate the problem further.

Symptom	Resolution
Body tracking works with controllers when running on the Meta Quest headset, but not with hands	Ensure you have enabled hand tracking permissions on your headset, under Settings > Movement Tracking > Hand Tracking. Also, in the Unreal Editor, ensure that Hand Tracking and Controllers are enabled in your project’s configuration.
Meta Horizon Link: Body tracking, face tracking, or eye tracking works when running an app directly on the headset as an Android build, but fails to run over Link.	1. Ensure connection with a USB cable that supports data transfer: Open Meta Horizon Link on the PC. 2. Under Devices, select your connected headset and verify the connection. 3. Ensure you have Developer Runtime Features enabled in Meta Horizon Link on the PC by navigating to Settings > Developer and enabling Developer Runtime Features. 4. Ensure that Eye Tracking over Meta Horizon Link and Natural Facial Expressions over Meta Horizon Link are enabled.
Body looks collapsed on the floor.	This means that Body tracking is not working. Outside of the app context, verify that controllers are being tracked, if you are using controllers. If you are using hand tracking, verify that hands are being tracked.
Character with body tracking rigged does not move or follow, neither controllers nor hands.	Animation Node: Ensure you have added a Start Body Tracking by Joint Set node during the start of your application (like pawn Begin Play). Actor Component: The Body Tracking component should automatically start the body tracking service on startup. Check that you have enabled body-tracking in the Meta XR plugin settings. Check that you are requesting the relevant permissions for body tracking.
Meta Horizon Link: When running the app on PC, it starts on PC, but doesn’t appear on the headset.	Check that Meta Horizon Link is enabled on the headset. Disconnect USB cable, connect it back, and enable Link again.
Tracking technologies fail to start via Link or built APKs even with tracking features enabled, and their permissions checks toggled.	Make sure that the account running on the headset and the app on PC is the same, and is a developer account with a team created. Refer to the Movement SDK overview for setup details.
Character has working body tracking but hovers up in the air or is down below ground.	Ensure you are correctly setting the Tracking Origin to Floor Level during your pawn’s begin play.
App crashes on startup	1. Ensure you have applied all recommended settings from the Meta XR project setup tool. 2. Ensure you are requesting the required permissions at the start of your application. 3. Ensure you are only requesting permissions that your device supports.
Unreal encounters compile issues when opening the Movement SDK Sample for Unreal	Make sure you have the latest version of the sample. Delete all temp-folders in the project root as well as under the plugin directory: Binaries, DerivedDataCache, Intermediate, Saved. You should now be prompted to rebuild the project when you open it next.

Debugging retargeting

Currently the visualizations described in this section are only available in non-shipping (Development/Debug) builds.

It is often useful to visualize the skeleton received from the tracking services (OculusXR Body Tracking skeleton) compared to the skeleton after you have completed the bone mapping and retargeting (retargeted skeleton). There are two fields added to the OculusXR Body Tracking node to support debug visualization. The Debug Pose Mode limits the debug to the rest pose.

The Debug Draw Mode provides five options:

None. Do not draw the debug skeleton.

Rest Poses. Draw only the rest poses.

Rest Pose With Mapping. Draw the rest pose and the adjustments made between the rest pose of the skeleton and the tracking skeleton.

Frame Pose. Draw the current frame pose as shown by the body tracking skeleton.

Frame Pose With Mapping. Draw the frame pose from the body tracking skeleton as modified by the adjustments to match the character.

Common errors like mapping the wrong bones should be immediately obvious and distinguishable from tracking errors. For instance, if you see a bone in the tracking skeleton behaving correctly, but the bone in the retargeted skeleton not moving, this likely indicates a naming mismatch in the bone mapping. The debug visualization renders the OculusXR Body Tracking skeleton in yellow, and the final retargeted output in green.

The retargeted algorithm depends on calculating offsets between the rest poses. As such there is another visualization provided for these skeletons with the following colors:

Yellow: The OculusXR Body Tracking rest pose / T-pose (tracking skeleton)

Green: Your skeletal mesh rest pose (retargeted)

This can help you understand which bones may need manual corrections.