SO100 Troubleshooting Guide: Common Issues and How to Fix Them

Running into problems with your SO100 robot arm? Don't worry — most issues have simple fixes. This guide covers the most common problems and step-by-step solutions.

---

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

1. Power supply connected? The 5V 3A power adapter must be plugged in and the LED on the driver board should be on.
2. USB cable connected? Use the included USB cable — some cables are charge-only and won't carry data.
3. Correct serial port? Run ls /dev/ttyUSB* (Linux) or ls /dev/tty.usb* (Mac) to find your port.
4. LeRobot installed correctly? Activate your conda environment: conda activate lerobot
5. Servos powered? You should hear a slight hum when servos are energized.

---

1. USB Device Not Detected

Symptoms: No /dev/ttyUSB* device appears. LeRobot throws a "port not found" error.

Fixes

Try a different USB cable. This is the #1 cause. Many USB-C cables are charge-only and don't support data transfer. Use the cable included in the kit or a known data-capable cable.

Check the driver board LED. If the LED on the Waveshare bus servo driver board is not lit, the board isn't receiving power. Verify the 5V power adapter is connected.

Install CH340 drivers. The driver board uses a CH340 USB-to-serial chip. Most modern systems auto-detect it, but you may need to install the driver manually:

• Linux: Usually built-in. Check with dmesg | grep ch34
• Mac: Download from the WCH website
• Windows: Download from the WCH website

Try a different USB port. USB hubs can cause issues. Connect directly to your computer's built-in USB port.

Check permissions (Linux). Run sudo chmod 666 /dev/ttyUSB0 or add your user to the dialout group: sudo usermod -aG dialout $USER (then log out and back in).

---

2. Servo Calibration Problems

Symptoms: Arm doesn't move to the expected positions. Joints are offset or range of motion seems wrong.

Fixes

Re-run calibration. Calibration tells LeRobot where each servo's zero position and range are. Run the calibration script:

python lerobot/scripts/control_robot.py calibrate \
  --robot-type so100 \
  --robot-overrides '~cameras' \
  --arms main_follower

Then repeat for main_leader.

Follow the calibration prompts carefully. During calibration, you'll be asked to move each joint to specific positions. Make sure you:

• Move the joint fully to each limit when prompted
• Keep the arm stable while positions are recorded
• Don't bump or shift the arm between steps

Check for stripped gears. If a servo moves freely without resistance (you can spin it by hand easily), the internal gears may be stripped. This is rare with normal use but can happen if the arm hits an obstruction at high speed. The fix is replacing the servo (~$12 for an STS3215).

Verify servo IDs. Each servo has a unique ID (1–6). If IDs got mixed up (e.g., during manual firmware updates), the arm will move unpredictably. Use the Waveshare servo debug tool or feetech_find_port.py to check IDs.

---

3. Servos Jitter or Vibrate

Symptoms: One or more servos shake, buzz, or oscillate in place instead of holding steady.

Fixes

Check your power supply. Servo jitter is almost always a power issue. The 5V 3A adapter included in the kit is correctly rated — if you're using a different power source, make sure it supplies at least 3A at 5V.

Reduce load. If the arm is trying to hold a heavy object or is at the extreme of its range, servos may struggle. Move the arm to a neutral position and see if jitter stops.

Check for mechanical binding. If a joint is physically obstructed (cables caught in the mechanism, over-tightened screws), the servo will fight against the resistance and jitter. Inspect the joints and free any obstructions.

Update servo parameters. In some cases, adjusting the PID gains on the STS3215 servos can reduce oscillation. This is an advanced fix — the default parameters work well for most setups.

---

4. LeRobot Installation Errors

Symptoms: pip install lerobot fails, or import lerobot throws errors.

Fixes

Use a fresh conda environment. LeRobot has specific dependency requirements. Create a clean environment:

conda create -n lerobot python=3.10 -y
conda activate lerobot
pip install lerobot

Check Python version. LeRobot requires Python 3.10+. Verify with python --version.

Install from source if pip fails. Sometimes the latest fixes haven't been published to PyPI yet:

git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e .

CUDA/GPU issues. If you see CUDA-related errors, make sure your PyTorch installation matches your GPU driver version. For CPU-only setups, this usually isn't an issue.

Mac ARM (M1/M2/M3) users. Some dependencies need special handling on Apple Silicon. Use conda install for numpy and scipy before installing LeRobot:

conda install numpy scipy -y
pip install lerobot

---

5. Teleoperation Not Working

Symptoms: You move the leader arm but the follower doesn't respond, or responds incorrectly.

Fixes

Make sure both arms are connected. You need two USB connections — one for the leader, one for the follower. Verify both ports are detected:

ls /dev/ttyUSB*
# Should show two devices, e.g., /dev/ttyUSB0 and /dev/ttyUSB1

Run teleoperation with the correct command:

python lerobot/scripts/control_robot.py teleoperate \
  --robot-type so100 \
  --robot-overrides '~cameras'

Calibrate both arms. If only one arm was calibrated, teleoperation will behave erratically. Calibrate both the leader and follower.

Check servo direction mapping. If the follower moves in the opposite direction from the leader on one axis, there may be a servo ID or configuration mismatch. Re-running calibration usually fixes this.

---

6. Camera Not Detected

Symptoms: LeRobot can't find or open the camera for recording demonstrations.

Fixes

Check the camera independently first. Open the camera with a standard tool to verify it works:

# Linux
ffplay /dev/video0

# Mac
ffplay -f avfoundation -i "0"

Find the right device index. If you have multiple cameras (e.g., laptop webcam + external camera), you may need to specify the correct index. List available cameras:

ls /dev/video*

Install OpenCV properly:

pip install opencv-python-headless

Remove the ~cameras override. If you were previously running with cameras disabled, make sure to remove the override flag when you want to use cameras.

---

7. Training Failures

Symptoms: python lerobot/scripts/train.py crashes, produces NaN losses, or the policy doesn't converge.

Fixes

Check your dataset. Bad training usually comes from bad data. Verify your recorded demonstrations:

• Were they smooth and consistent?
• Did the arm actually complete the task in each episode?
• Were there at least 20–50 episodes for a simple task?

Start with ACT policy. If you're new to LeRobot, start with the ACT (Action Chunking with Transformers) policy — it's the most forgiving for simple tasks:

python lerobot/scripts/train.py \
  --policy.type=act \
  --dataset.repo_id=your_username/your_dataset

Reduce batch size if you run out of memory:

python lerobot/scripts/train.py \
  --policy.type=act \
  --training.batch_size=8 \
  --dataset.repo_id=your_username/your_dataset

Check GPU memory. Training with the default settings requires ~6GB of VRAM. If you have less, reduce the batch size or use a smaller model.

---

8. Arm Moves Erratically During Playback

Symptoms: A trained policy runs but the arm jerks, overshoots, or misses targets.

Fixes

Record more demonstrations. Most policy failures come from insufficient training data. For a simple pick-and-place task, aim for 50+ demonstrations.

Ensure consistent setup. The arm, objects, and camera must be in the same positions as during data collection. Even small changes in camera angle or object placement will degrade performance.

Slow down the control frequency. The default 30Hz control rate may be too fast for some tasks:

python lerobot/scripts/control_robot.py replay \
  --robot-type so100 \
  --fps 20

Train for more epochs. The default training may not be enough for your task. Try doubling the number of training steps.

---

9. Physical Assembly Issues

Symptoms: Parts don't fit, screws are missing, or the arm feels loose.

Fixes

The SO100 Complete Kit ships pre-assembled, so assembly issues should be minimal. If something came loose during shipping:

• Tighten M2 screws with the included hex key. Don't over-tighten — the 3D-printed parts can crack.
• Check servo horn alignment. The metal servo horns should be centered. If one is offset, loosen the horn screw, recenter, and retighten.
• Base stability. Mount the base to a flat surface with the included clamp or tape. An unstable base causes accuracy issues.

If you purchased a DIY kit or 3D-printed your own parts:

• Check print quality — layer adhesion and dimensional accuracy matter.
• Sand any tight-fitting joints gently with fine-grit sandpaper.
• Use the official STL files from the SO100 GitHub repository.

---

10. Servo Overheating

Symptoms: Servos become very hot to the touch after extended use.

Fixes

This is normal during sustained operation. STS3215 servos generate heat, especially under load. They're rated for continuous operation, but:

• Take breaks during long sessions (5 minutes every 30–45 minutes).
• Don't leave the arm energized and stationary for long periods. If you're not actively using it, power off or put servos in a relaxed state.
• Ensure airflow. Don't enclose the arm in a tight box during operation.

If a servo shuts down from overheating, it will restart automatically once it cools. This is a safety feature, not a defect.

---

Still Stuck?

If your issue isn't covered here:

1. Check the LeRobot GitHub Issues — many common problems have been discussed and resolved by the community.
2. Search the Hugging Face Discord — there's an active #lerobot channel where users and maintainers help each other.
3. Email us at so100@nanocorp.app — we're happy to help troubleshoot.

---

Prevention: Tips for a Smooth Experience

• Always power off before disconnecting USB. Hot-unplugging can corrupt servo settings.
• Calibrate after any firmware updates. Servo parameters may change.
• Keep your LeRobot installation updated. The project moves fast — bugs get fixed regularly.
• Record demonstrations in good lighting for camera-based policies.
• Start with simple tasks (pick and place, push) before attempting complex multi-step sequences.

The SO100 is a robust, well-tested platform used by 50+ universities and hundreds of makers worldwide. Most issues have simple fixes — and the community is always there to help.

Get the SO100 Complete Kit — $199 (Launch Special) →