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 seeMost likely areaStart with
Port exists, but LeRobot cannot connectPort permissions or incorrect port mappingRun lerobot-find-port, then check permissions
Motor 'gripper' was not foundServo wiring, power, ID, or baud rateConnect only the gripper servo and retry setup
There is no status packet!Servo-bus power, cable, or duplicate/missing IDCheck LEDs and test the servo chain one section at a time
Magnitude exceeds 2047Incorrect midpoint or stale calibrationRecalibrate the servo midpoint and the complete arm
Teleoperation drifts or jittersCalibration, power, mechanics, or bus communicationConfirm teleoperation before collecting data
No valid stream foundIncorrect FFmpeg installationVerify which ffmpeg and install the validated version
Camera not found or frame timeoutSerial number, USB bandwidth, or connectionRun camera discovery and reconnect directly to USB
Recording hotkeys do not workpynput or graphical-session issueInstall the compatible version and check $DISPLAY
Training fails with a Column errorIncompatible datasets versionInstall datasets==2.19
Trained policy performs poorlyDataset quality, diversity, or inference settingsReview 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

  1. Pre-flight hardware and software checks
  2. Serial-port connection failures
  3. Missing gripper servo during ID setup
  4. Servo-bus and no status packet errors
  5. Calibration and abnormal joint-angle errors
  6. Teleoperation drift, jitter, and disconnection
  7. FFmpeg video errors
  8. Camera detection and timeout problems
  9. Data-collection keyboard controls
  10. Training dependency errors
  11. Poor real-world policy performance
  12. Compute and Jetson requirements
  13. 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:

  1. 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.
  2. 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.
  3. Connect both USB and external power. USB provides communication; it does not power the complete servo bus.
  4. Identify the correct serial ports. Leader and Follower each use a port. Do not guess their roles from names such as ttyACM0 and ttyACM1. Run lerobot-find-port and follow the unplug/reconnect prompt.
  5. 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

  1. 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.
  2. Verify power. Check the adapter, DC connector, and controller input. Ensure the Leader and Follower power supplies have not been swapped.
  3. Confirm port mapping. With both arms connected, run lerobot-find-port again to ensure the Leader port is not used in the Follower configuration.
  4. Reduce the bus. Power off, test one servo, and reconnect the remaining servos one at a time to identify the failing segment.
  5. 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:

  1. Power off and manually move every joint near the midpoint shown in the assembly guide.
  2. Recalibrate the midpoint of the abnormal servo; the current position should be stored as 2048.
  3. Verify that the servo ID, model, and gear ratio match the joint position.
  4. 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:

  1. Repeat servo midpoint calibration and full-arm calibration.
  2. Verify Leader/Follower power and serial-port mapping.
  3. Ensure a motor-initialization command did not overwrite existing servo IDs.
  4. 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=50
  • chunk_size_threshold=0.5
  • aggregate_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:

  1. Stop the program.
  2. Disconnect and reconnect the camera.
  3. Connect directly to a high-speed USB port instead of an unstable passive hub.
  4. 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:

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.

About Author

Leave a Reply

Your email address will not be published. Required fields are marked *

Calendar

November 2026
M T W T F S S
 1
2345678
9101112131415
16171819202122
23242526272829
30