Troubleshooting

Work through this in order. The first section decides whether you have a network problem or a data problem, and they need completely different fixes.

The row never turns green

Nothing is arriving. Nothing about coordinates or calibration matters yet.

Check	How
Is Unity in Play mode?	The provider only listens while playing.
Do the ports match?	Port in the UDP row and --port on the sender. Both default to 9750.
Is the sender actually running?	It prints a sample count as it streams. No output, no packets.
Firewall?	Windows prompts the first time Unity opens a port. If you dismissed that prompt, allow Unity inbound UDP in Windows Defender Firewall.
Right machine?	Sending to another machine needs --host <its IP>, and both machines on the same network. 127.0.0.1 only works when the sender and Unity are on the same computer.

Try the bundled sample on the same machine with default settings. If that works, the pipeline is fine and the problem is in your sender or your network path.

The row goes green, then red

Packets arrived and stopped. Tracking reads as lost 1.5 seconds after the last one.

• The sender finished. Recordings end. Use --loop to repeat.
• The sender crashed. Check its terminal for a traceback.
• Wi-Fi. UDP has no retransmission, so a congested wireless link drops packets silently. Use a wired connection for sessions that matter.

It moves, but the pose is wrong

Now it is a data problem. Turn on Gizmos → Joints, Bones and Axis first — the gizmo skeleton is the pose before any avatar is involved, and judging through a character adds a second thing that can be wrong.

Then match the symptom:

What you see	Cause	Fix
Not a plausible body — joints scattered	Quaternion order	Try the other setting. XYZW for processed CSVs, WXYZ for raw sensor exports.
Upside down, lying down, or mirrored	Axis conversion	Set it to your sender's convention — see Coordinate frames.
Arms out sideways when they should hang down	Calibration pose	Set it to the pose the participant actually held.
Constant offset at every joint	Reference captured mid-movement	Enter Play mode before starting the sender, or press Recapture while they hold still.
Reaches land in the wrong direction — a forward reach goes across the body, a drink arrives beside the ear	Heading offset	Run estimate_imu_heading.py --dataset <folder>, or sweep until a forward reach moves the avatar forward.
Only some joints move	Missing sensors, or channel map	Expected if your rig has fewer sensors. See Wire format.
Joints in the right place, twisted oddly	Axis conversion close but not exact	Try the other options; check the source's documented convention.

Fix them in that order. A wrong axis conversion makes heading impossible to judge, so sweeping heading first wastes time.

Heading is worth its own note, because it is the one setting whose symptom looks like a rigging problem rather than a settings problem. The motion comes out the right shape in the wrong plane: every joint bends by the correct number of degrees, so nothing about the pose looks broken, but the participant's whole plane of movement is rotated away from the avatar's forward. It is also the setting people most often blame on something else — the calibration pose, or how the sensors were taped on. Neither can cause it. Sensor mounting cancels exactly in the neutral-pose reference, so rotating a sensor on the limb, palm included, changes the result not at all.

Wrong joints move

The right elbow bends when the participant bends their left, or an arm sensor drives a leg.

Your sender's channel order does not match Quaternion channels. The usual cause is a rig with fewer than 17 sensors sending its values in the first N slots. Send all 17 and put a zero quaternion in the slots you have no sensor for — see Sending fewer sensors.

Motion is jerky or stepped

• Send rate too low. Below roughly 30 Hz, steps become visible. Send at your source's native rate.
• Packets being dropped. Wireless, or a sender outrunning the network. Try a wired connection or a lower rate.
• The recording is low rate. A 30 Hz recording looks like 30 Hz however fast you send it.

The avatar is wrong but the gizmos are right

The tracking is fine; the problem is the character. See Avatars and Avatar Calibrations.

This split is the reason to turn gizmos on before debugging anything. A character sits between you and the data and can be wrong on its own.

Isolating the problem

When you are unsure which half is at fault, remove one half at a time:

1. Set the provider to Synthetic. If the avatar still misbehaves, the problem is the avatar — no network or sender involved.
2. Run the bundled sample. If it dances correctly, LABO is configured correctly and the problem is in your data or sender.
3. Run your data through the sample's script with --data. If it works there but not from your own sender, the problem is your sender's packet format.

Each step removes one variable. Changing settings while several things could be wrong is how an afternoon disappears.