SO-ARM101 LeRobot Troubleshooting Guide: From Setup and Calibration to Training and Deployment
Fix common SO-ARM101 and LeRobot issues, including serial-port errors, missing servos, calibration failures, camera timeouts, dataset problems, and unstable inference.
The SO-ARM101 is a low-cost, open-source robot arm for LeRobot, imitation learning, and embodied AI. It supports the complete workflow from teleoperation and data collection to policy training and real-world inference.
If your arm cannot connect, a servo is missing, calibration fails, the camera times out, or the trained policy performs poorly, start here. This guide organizes the most common problems by symptom and gives you a practical order in which to diagnose them.
For assembly diagrams, full commands, parameter explanations, and the latest version-specific instructions, use this article together with the official SO-ARM100/SO-ARM101 LeRobot Wiki.
Safety warning: Secure the robot arm and clear people, cables, tools, and fragile objects from a one-meter area before running any command that may move the robot. Always disconnect power before plugging or unplugging servo, USB, or power cables.
Quick Diagnosis: Find Your Problem First
| What you see | Most likely area | Start with |
|---|---|---|
| Port exists, but LeRobot cannot connect | Port permissions or incorrect port mapping | Run lerobot-find-port, then check permissions |
Motor 'gripper' was not found | Servo wiring, power, ID, or baud rate | Connect only the gripper servo and retry setup |
There is no status packet! | Servo-bus power, cable, or duplicate/missing ID | Check LEDs and test the servo chain one section at a time |
Magnitude exceeds 2047 | Incorrect midpoint or stale calibration | Recalibrate the servo midpoint and the complete arm |
| Teleoperation drifts or jitters | Calibration, power, mechanics, or bus communication | Confirm teleoperation before collecting data |
No valid stream found | Incorrect FFmpeg installation | Verify which ffmpeg and install the validated version |
| Camera not found or frame timeout | Serial number, USB bandwidth, or connection | Run camera discovery and reconnect directly to USB |
| Recording hotkeys do not work | pynput or graphical-session issue | Install the compatible version and check $DISPLAY |
Training fails with a Column error | Incompatible datasets version | Install datasets==2.19 |
| Trained policy performs poorly | Dataset quality, diversity, or inference settings | Review episodes before increasing training steps |
Recommended Troubleshooting Order
Power and wiring → USB ports and permissions → servo IDs and midpoint
→ full-arm calibration → teleoperation → cameras → dataset
→ training environment → real-world inference
Finish each stage before moving to the next. A calibration or communication problem will not be fixed by collecting more data or training for longer.
In This Guide
- Pre-flight hardware and software checks
- Serial-port connection failures
- Missing gripper servo during ID setup
- Servo-bus and
no status packeterrors - Calibration and abnormal joint-angle errors
- Teleoperation drift, jitter, and disconnection
- FFmpeg video errors
- Camera detection and timeout problems
- Data-collection keyboard controls
- Training dependency errors
- Poor real-world policy performance
- Compute and Jetson requirements
- Choosing the right SO-ARM101 kit
1. Before You Start: Five Essential Checks
Many apparent software errors are actually caused by wiring, power, or incompatible versions. Check the following first:
- Use the repository validated by the tutorial. Follow the Wiki and clone
https://github.com/Seeed-Projects/lerobot.git. Upstream LeRobot changes quickly, so commands, parameters, dependencies, and dataset formats may differ between releases. Avoid mixing instructions and code from different versions. - Verify the robot model and supply voltage. The SO-ARM101 Leader uses 7.4 V series servos. Depending on the kit, the Follower may contain 7.4 V or 12 V servos. Check the servo labels and product documentation before applying power. An incorrect voltage may prevent operation or damage the hardware.
- Connect both USB and external power. USB provides communication; it does not power the complete servo bus.
- Identify the correct serial ports. Leader and Follower each use a port. Do not guess their roles from names such as
ttyACM0andttyACM1. Runlerobot-find-portand follow the unplug/reconnect prompt. - Complete calibration and teleoperation before recording data. If teleoperation drifts, jitters, or disconnects, data collection will only carry those hardware and calibration problems into the dataset.
2. Serial Port Exists, but LeRobot Cannot Connect
Symptom
Could not connect on port "/dev/ttyACM0"
The device may appear as /dev/ttyACM0, but LeRobot cannot open it.
Fix it step by step
Confirm that the port exists:
ls /dev/ttyACM*
Identify the actual Leader and Follower ports:
lerobot-find-port
If the ports exist but the current user lacks permission, temporarily run:
sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1
Then retry calibration or teleoperation. If permissions disappear after a reboot, configure a persistent udev rule.
If it still does not connect
Check whether:
- Leader and Follower ports were swapped;
- the USB cable supports data instead of charging only;
- the controller board has external power;
- another application is holding the port;
- the USB connector or hub is unstable.
See the servo calibration and assembly section of the official Wiki for the complete setup flow.
3. Gripper Servo Is Missing During Motor Setup
Symptom
Motor 'gripper' was not found, Make sure it is connected
Likely causes
- The gripper servo is not connected directly to the controller board.
- The three-wire servo cable is reversed, loose, or making poor contact.
- The servo has no power or receives the wrong voltage.
- Multiple unconfigured servos are connected to the bus at the same time.
- The servo ID or baud rate was changed previously.
Fix it step by step
When running lerobot-setup-motors, follow every terminal prompt. When the program asks for the gripper, the chain should be:
Computer → USB data cable → servo controller → three-wire cable → gripper servo
The gripper must be the only servo connected to the controller at this stage. Power off, reseat the cable, restore power, and press Enter. After configuring one servo, power off again before connecting the next.
If detection still fails, use the SoARM servo debugging tool described in the Wiki to inspect the servo, restore its ID, and set its current position as the midpoint value 2048.
4. Servo Position Read Fails with No Status Packet
Symptom
ConnectionError: Failed to sync read 'Present_Position' on ids=[1,2,3,4,5,6]
[TxRxResult] There is no status packet!
This means the controller sent a read request, but the servo bus did not return a complete response.
Fix it step by step
- Check the LEDs. If one servo is not lit, inspect that servo and the cable from the preceding servo. Pay particular attention to the short cable between joints 4 and 5.
- Verify power. Check the adapter, DC connector, and controller input. Ensure the Leader and Follower power supplies have not been swapped.
- Confirm port mapping. With both arms connected, run
lerobot-find-portagain to ensure the Leader port is not used in the Follower configuration. - Reduce the bus. Power off, test one servo, and reconnect the remaining servos one at a time to identify the failing segment.
- Check IDs and baud rate. IDs 1–6 must be unique and present, and all servos must use the baud rate expected by the tutorial.
If the error remains reproducible, record the servo LEDs and wiring, save the complete terminal output, and provide both to technical support.
5. Calibration Fails or a Joint Moves to an Abnormal Angle
Symptom
Magnitude 30841 exceeds 2047 (max for sign_bit_index=11)
Related symptoms include MAX values in the tens of thousands, teleoperation drift, or a joint suddenly moving in the wrong direction.
Fix it step by step
Stop the program, power-cycle the robot, and retry calibration. If the problem remains:
- Power off and manually move every joint near the midpoint shown in the assembly guide.
- Recalibrate the midpoint of the abnormal servo; the current position should be stored as
2048. - Verify that the servo ID, model, and gear ratio match the joint position.
- Discard the previous calibration result and recalibrate the complete arm.
When the terminal displays:
Press ENTER to use provided calibration file ... or type 'c' and press ENTER to run calibration
Type c and press Enter to recalibrate. Pressing Enter alone reuses the existing calibration. Do not reuse an old file after observing drift or abnormal angles.
A raw encoder value wrapping between 4095 and 0 does not necessarily indicate damaged hardware. Repeating the midpoint calibration often resolves the issue.
6. Teleoperation Drifts, Jitters, Stops, or Disconnects
Case A: The Follower drifts or does not move
Check the following in order:
- Repeat servo midpoint calibration and full-arm calibration.
- Verify Leader/Follower power and serial-port mapping.
- Ensure a motor-initialization command did not overwrite existing servo IDs.
- Compare the hardware against the SO-ARM100/SO-ARM101 model table and confirm the correct gear-ratio configuration for the first three Leader joints.
Case B: Motion jitters or policy inference pauses
First determine where the problem begins:
- Teleoperation also jitters: inspect mechanical assembly, power, servo parameters, and bus communication.
- Teleoperation is smooth but policy inference stutters: inspect compute performance, inference frequency, camera resolution, and the action queue.
For policy inference, try asynchronous inference and start with:
actions_per_chunk=50chunk_size_threshold=0.5aggregate_fn_name=weighted_average
If the action queue frequently runs empty, increase actions_per_chunk or chunk_size_threshold. You can also reduce execution FPS, camera resolution, or frame rate. See the asynchronous inference guide for the complete command and parameter explanation.
Case C: The gripper disconnects at its mechanical limit
Do not hold the gripper against its hard stop. Reduce gripper torque or narrow the control range. If the issue occurs repeatedly, check servo firmware, power stability, and the condition of the gripper servo.
7. FFmpeg Cannot Find a Valid Video Stream
Symptom
No valid stream found in input file. Is -1 of the desired media type?
Fix it step by step
Check which FFmpeg installation the active environment uses:
which ffmpeg
ffmpeg -version
ffmpeg -encoders
Install the version validated by the Wiki inside the LeRobot conda environment:
conda install ffmpeg=7.1.1 -c conda-forge
Open a new terminal, activate the same conda environment, and confirm that which ffmpeg points to its executable. Avoid mixing system FFmpeg, conda FFmpeg, and executables from other Python environments.
8. Camera Detection, Timeout, and Missing-View Problems
Case A: Orbbec reports No Orbbec camera found
The configured serial number may not match the connected device. Run:
lerobot-find-cameras orbbec
Copy the detected value into serial_number_or_name in the camera configuration.
Case B: Orbbec frame timeout
If increasing the USBFS buffer does not solve the timeout:
- Stop the program.
- Disconnect and reconnect the camera.
- Connect directly to a high-speed USB port instead of an unstable passive hub.
- Run camera detection again before starting teleoperation or recording.
Case C: RealSense on macOS reports failed to set power state
Running the same detection command with sudo may help. RealSense stability on macOS can still be limited, so Linux is recommended for reliable real-world data collection.
Case D: Rerun displays only one camera during dual-camera recording
This does not necessarily indicate missing data. In Rerun, right-click the left sidebar, add another camera view, and drag the second image stream into it.
9. Data-Collection Hotkeys Do Not Respond
During recording, Right Arrow ends the current episode or starts the next one, Left Arrow re-records an episode, and Esc exits. If none of these keys work, try the compatible pynput version:
pip install pynput==1.6.8
On Linux, verify that $DISPLAY is set and run the command inside a graphical session capable of receiving keyboard events. Keyboard capture may fail in a pure SSH session, container, or headless environment.
Before recording a large dataset, create two or three test episodes and confirm that:
- both camera streams are saved;
- joint actions and video frames are synchronized;
- end, re-record, and exit controls work;
- playback is safe and matches the demonstration.
10. Training Fails with a PyTorch Column Error
Symptom
TypeError: stack(): argument 'tensors' (position 1) must be tuple of Tensors, not Column
Fix
This is commonly caused by an incompatible datasets version. Install the version validated by the tutorial in the active LeRobot environment:
pip install datasets==2.19
Record or lock dependency versions afterward so an unrestricted upgrade does not recreate the issue. If the error continues, confirm that the repository, dataset format, and training command all come from the same tutorial version.
11. The Trained Policy Performs Poorly on the Real Robot
Do not focus only on loss or blindly increase the training steps. Diagnose the problem in this order.
Step 1: Inspect data quality
- Remove episodes containing failure, collision, long pauses, or visible jitter.
- Start demonstrations from reasonably consistent initial states.
- Prevent camera movement, autofocus hunting, and sudden exposure changes.
- Keep the target object inside the usable field of view.
- Make demonstrations stable, concise, and consistent.
Step 2: Add useful diversity
For a simple pick-and-place task, begin with approximately 40–50 episodes that cover different object positions. If success remains low, add more valid demonstrations and vary position, lighting, and background moderately.
Avoid directly combining a dataset recorded on another setup. Different camera poses, robot calibration values, and scenes can significantly reduce performance.
Step 3: Tune training and inference only after fixing the data
ACT is a practical first baseline. Community experience suggests that roughly 40,000 steps and 50 high-quality demonstrations can produce initial results on simple tasks, although training time depends on the GPU and task complexity.
If loss does not meaningfully decline, consider additional training steps. If offline results look reasonable but real-world motion pauses, investigate synchronous/asynchronous inference settings and local compute performance first.
For complete commands and entry points for ACT, SmolVLA, π0, GR00T, and other policies, see the training and evaluation section of the Wiki.
12. Hardware Requirements: Do You Need Jetson or a High-End GPU?
Not for every stage.
- Assembly, calibration, teleoperation, and recording: A compatible Ubuntu computer can complete these tasks; Jetson is not mandatory.
- Local training: An NVIDIA GPU is recommended. Smaller policies such as ACT are easier starting points, while larger VLA models generally require more VRAM or cloud compute.
- Edge deployment: Jetson is useful when inference must run near the robot, when no suitable Ubuntu/NVIDIA GPU workstation is available, or when a more integrated deployment environment is preferred.
Windows, WSL, and virtual machines may introduce USB passthrough, serial permission, and real-time performance issues. For reliable physical data collection, native Ubuntu is the preferred environment.
13. Buying Guide: Which SO-ARM101 Kit Should You Choose?
SO-ARM101 is well suited to developers, educators, and researchers who want an affordable way to explore LeRobot imitation learning, embodied AI, or robotics prototyping.
Consider the following before purchasing:
- Motor kit or assembled arm: A motor kit is ideal if you want to learn servo configuration and mechanical assembly. An assembled kit removes most assembly work, although software setup and full-arm calibration are still required.
- Standard or Pro: Follower servos and supply voltage may differ between versions. Always follow the labels and current product specification for the kit you receive.
- Cameras: Imitation learning needs stable USB camera views. A 32 × 32 mm UVC module can be used as a wrist camera, while a standard USB webcam can provide the global view.
- 3D-printed parts: A motor kit may not include printed structures or cameras. Check the package contents before ordering.
Ready to start teleoperation, data collection, and imitation learning with SO-ARM101? Explore the available kits on Seeed Studio Bazaar:
- SO-ARM101 Pro Servo Motor Kit — for users printing their own structural parts
- SO-ARM101 Pro Assembled Kit
- SO-101 Imitation Learning Kit — robot arms, cameras, and mounting accessories
Before ordering, confirm the latest package contents, voltage requirements, stock status, and shipping availability on the product page.
Final Checklist Before You Run the Robot Again
Before retrying teleoperation, data collection, or inference, confirm that:
- the Leader and Follower use the correct power supplies and serial ports;
- all servo LEDs are on and IDs 1–6 are unique;
- midpoint calibration and full-arm calibration complete without abnormal values;
- teleoperation is smooth before any episode is recorded;
- every required camera is detected and produces a stable stream;
- the code, dataset format, and dependency versions belong to the same LeRobot setup;
- the test area is clear and the robot can be stopped safely.
Get the Complete SO-ARM101 Setup Instructions
The fastest way to solve an SO-ARM101 problem is to work from the physical layer upward: power, wiring, communication, calibration, teleoperation, cameras, data, training, and finally inference.
For complete assembly images, configuration examples, commands, camera setup, data collection, policy training, evaluation, and the latest FAQ updates, visit the official Seeed Studio SO-ARM100/SO-ARM101 LeRobot Wiki.
If you are preparing a new setup, compare the available SO-ARM101 kits on Seeed Studio Bazaar and verify the current package contents and voltage specifications before ordering.