Why is my USB camera not detected, or dropping out mid-recording?

Three failures, one complaint

ay-robots devices

# SERIAL PORTS
#   robot_1   unknown
# CAMERAS
#   camera_1  USB 2.0 Camera
#   camera_2  UGREEN Camera 2K (gripper)

Bandwidth is the usual answer

A USB camera that streams uncompressed frames reserves bandwidth on its controller for as long as it is open, whether or not anything is looking at the frames. The reservation is made up front, and if the controller cannot satisfy it, the camera does not start. That is the mechanism behind the most common report on this page: two cameras that each work perfectly on their own and refuse to work together.

The trap is that USB sockets are not independent. Several physical ports on a machine usually hang off one controller and share its budget, and which ports share is not something you can tell by looking at the case. Two ports right next to each other may be one controller; a port on the opposite side of the laptop is often a different one. This is why "I moved it to another port and nothing changed" is such a common second sentence.

The levers, roughly in order of how well they work: put the second camera on a genuinely different controller, add a powered hub so the hub arbitrates and supplies its own power, lower the resolution of whichever camera matters least, and prefer a camera that can deliver a compressed stream, since compressed video needs a fraction of the budget that raw frames do. Two cameras at moderate resolution is an ordinary setup that works on ordinary hardware. The difficulty scales with pixels per second, not with the number of devices.

# Linux: which controller does each port hang off
lsusb -t

# Linux: what the kernel calls each camera, and its capabilities
v4l2-ctl --list-devices

# The platform view of the same hardware
ay-robots devices

Labels only bind if a camera carries the label

When you pass --cameras wrist,top, each name is looked up against the cameras the platform knows about: it matches if the name appears inside a camera’s id or inside its reported name, compared in lower case. A name that matches nothing is not an error. The recorder falls back to taking the next camera that is still free, in scan order, and carries on.

That fallback is where the quiet column swap comes from. Scan order follows device paths, and device paths move after a replug, after a reboot, or after waking with a hub attached. So as long as no camera is actually called wrist, the words wrist and top are only two column names in your dataset, filled in whatever order the scan produced that day. Nothing warns you, because from the system’s point of view nothing went wrong.

The consequence for recording is expensive and delayed. If the scan order flipped between Monday and Wednesday and both sessions went into the same dataset, then half your episodes have the wrist view in the scene column and the other half do not. Nothing crashes. Training runs. The policy is asked to make sense of two contradictory views of the world and does poorly, and the cause is three weeks upstream by the time you look for it.

The fix is to rename the camera to the label you intend to use. Renaming changes the id the platform keeps for that device, which is stored against its hardware id and therefore survives reboots, so afterward the device list shows wrist next to the camera model and the label binds to that specific camera instead of to a position in a queue. There is no CLI command for renaming, and there is no rename in the desktop client either: it is done on the Hardware page for your robot in the dashboard, in the device list at the top, where every camera and every arm carries a small edit control next to its id. The camera dropdown in the client’s settings is a different list, built from what the operating system hands the client’s own webview, so the entries you pick there are not the ids a label is matched against. Then record one throwaway episode and look at the column names before you commit a session to them.

ay-robots record --task "pick up the red cube and place it in the bowl" \
  --dataset cube_pick \
  --episodes 10 \
  --cameras wrist,top

Only one process gets the camera

In practice a camera is exclusive: the first process to open it holds it, and everything after that is refused or handed nothing. The refusal is rarely reported as clearly as it should be, so the second consumer typically shows the camera in its list and then produces black frames, which reads as a broken camera.

The usual holders are a video call application minimized in the background, a browser tab that was granted camera permission and never released it, a preview window you opened yourself and forgot, and an earlier instance of the client that did not exit cleanly. A policy that is still running counts too, since the inference loop opens a camera and only gives it back when the loop is stopped. Rule all of that out before you touch the hardware.

# What the local backend is doing: hardware, simulation or demo, and
# whether it is idle, teleoperating or running a model. A backend that
# is running a model has a camera open.
ay-robots status

# After closing the other consumers, rescan
ay-robots devices

Work through it in this order

1. 1
   Scan and note what is actually listed

   A camera that is missing from the list and a camera that is listed but black are different problems. Do not skip this distinction, it halves the search.

   bash

   ay-robots devices

2. 2
   Unplug every camera but the failing one

   If it works alone, the camera is fine and you have a bandwidth or contention problem. If it fails alone on a known-good port, the camera or its cable is the suspect.

3. 3
   Close everything else that could hold a camera

   Video calls, browser tabs with camera permission, any preview window, any second copy of the client. Then rescan before changing anything physical.

4. 4
   Move the camera to a port on the other side of the machine

   You are trying to land on a different controller. On Linux, lsusb -t tells you whether you succeeded instead of leaving you to guess.

5. 5
   Put it on a powered hub

   A powered hub supplies its own current and often resolves both the bandwidth contention and the slow dropouts that come from a laptop port supplying two cameras and an arm adapter.

6. 6
   Shorten the cable, remove extensions

   Long unpowered extensions are a leading cause of "worked for five minutes then stopped". Test with the shortest cable you own before concluding anything about the camera.

7. 7
   Reduce the pixel rate

   Lower the resolution of the camera that contributes least, or use one that delivers a compressed stream. This is the lever that makes an over-subscribed controller viable without buying anything.

8. 8
   Rename the cameras, then record one throwaway episode

   Give each camera the name you pass to record, then confirm that the right view landed in the right column before you commit a session to it. One test episode is cheap; discovering a swapped camera after fifty is not.

   bash

   ay-robots record --task "camera check" --episodes 1 --cameras wrist,top

What a dropout does to an episode

The recorder does not leave a hole. It holds the newest complete camera snapshot and writes that same snapshot again whenever a fresh one is not ready, so a camera that stops delivering produces a run of byte-identical repeat frames, not a gap. The episode therefore looks intact: the check that runs when an episode is saved counts one JPEG per camera against the number of rows in the parquet file, and repeated frames satisfy that count exactly. A camera that falls out of the capture entirely does fail that count, and then the save is refused and the artifacts are moved to a quarantine folder rather than written into the dataset, so the case you have to catch yourself is the quiet one. The recorder does report it: dropped_camera_frames comes back with every saved episode and counts frames written with no image at all, the recording status carries a separate stale_camera_frames count for every tick where a snapshot had to be reused, and the web cockpit raises a warning while you are still recording once camera frames start going missing or arriving incomplete. Treat any of those as a reason to discard the session, because a policy trained on frozen frames learns that the scene holds still while the arm keeps moving. Review episodes before you keep them, and throw away anything recorded during a session where a camera was dropping. The reasoning behind the review habit is on /learn/record-your-first-dataset, and the composition of a usable dataset is on /so-100/data-collection.

Frequently asked questions