3D visionTroubleshooting

Depth camera failed to boot: X_LINK_UNBOOTED fix without a reboot

What X_LINK_UNBOOTED means when a USB depth camera failed to boot after a close, and how a USB port reset recovers it in seconds without rebooting the host.

LumaSpec Vision9 min read Share on LinkedIn

On this page 9 sections
  1. 01What X_LINK_UNBOOTED tells you
  2. 02Four causes, in order of likelihood
  3. 03Recover in seconds: reset the port, not the PC
  4. 04Stop it coming back
  5. 05The downtime arithmetic
  6. 06Which fix, when
  7. 07When the port reset is the wrong answer
  8. 08Checklist before you call it fixed
  9. 09Questions

You stop your depth camera application, start it again minutes later, and the open call fails with X_LINK_UNBOOTED, wrapped in a runtime error that reads "Failed to boot device". lsusb still lists the camera, dmesg shows it enumerating, and only a host reboot clears the wedge. The camera is not dead: the previous process left the device in a half-booted state that the next open cannot boot over. This guide gives you the five-second recovery that replaces the reboot, the close and udev habits that stop the wedge coming back, and the decision path for the cases where the USB port is the wrong layer to fix.

A depth camera speaking the XLink USB protocol has two lives on the bus. In its pre-boot state it enumerates as a plain USB device — in this failure, vendor ID 03e7, product 2485 — and does nothing until the host library uploads the runtime firmware that runs the depth pipeline. X_LINK_UNBOOTED is raised when the library finds the device on the bus but the firmware start never completes: enumeration succeeded, the boot handoff did not.

That split tells you where to work. The USB layer is healthy enough to enumerate; only the handoff is wedged. Rebooting the PC clears it because the controller resets the port, dropping the camera back to pre-boot state — and that state is reachable in software, without the reboot.

The trigger is almost always the run before the failure. A process killed with kill -9, interrupted past its cleanup, or a viewer closed from the taskbar exits without closing the device. The camera is left neither cleanly pre-boot nor properly running, and the next open boots into that stuck state and fails.

Four causes, in order of likelihood

  1. Unclean close of the previous run. Crashes and interrupts skip the close call that returns the device to pre-boot state. Test: run the camera, kill -9 the process, reopen — if the error appears, you have reproduced it. The finally-block close further down removes most of this class.

  2. USB autosuspend. Between runs, kernel power management suspends the interface, and some depth devices never resume into a bootable state. Test: cat /sys/bus/usb/devices/1-2/power/control — a value of auto means the port may sleep. The udev rule below pins it to on.

  3. A marginal USB 3 link. A USB 3 depth camera that always enumerates as high-speed is running at USB 2.0 speed — 480 Mbit/s instead of the 5 Gbit/s of the 3.0 link — so the SuperSpeed pairs are not training and long boot transfers fail part-way. The full diagnosis is in a camera enumerating as USB 2.0 on a USB 3.0 port. If dmesg also shows error -71, move the cable to first place: that signature is covered in USB disconnect errors -71 in dmesg.

  4. Host controller quirk. A minority of on-board USB controllers mishandle the re-boot handoff after an unclean close. Test: a port on a different controller, or a second host. If the failure follows the port and not the camera, move the camera; to map the host side methodically, start with diagnosing the host path of a USB camera that will not enumerate.

Recover in seconds: reset the port, not the PC

  1. Confirm the camera is still on the bus and note its IDs:
lsusb

You are looking for the depth pair — 03e7:2485 here; substitute your own. If lsusb no longer lists the camera at all, it has dropped off the bus: that is a power or link failure, not an unbooted device, and the cable path below applies.

  1. Reset the device with usb_modeswitch:
sudo usb_modeswitch -R -v 03e7 -p 2485

-R applies a USB reset to that one device. The port re-enumerates, the camera lands in pre-boot state, and dmesg prints a fresh device line within about a second.

  1. Without usb_modeswitch, do the same through sysfs. Find the camera's bus-port address in dmesg — a line like usb 1-2: new high-speed USB device gives you 1-2 — then detach and re-attach it:
echo '1-2' | sudo tee /sys/bus/usb/drivers/usb/unbind
echo '1-2' | sudo tee /sys/bus/usb/drivers/usb/bind

The unbind removes the device from the bus; the bind restores it, freshly enumerated. This path is also the dependable one on boards that keep the port powered across a replug — the reason a replug sometimes changes nothing is covered in USB VBUS staying on.

  1. Reopen your application. One reset clears the wedge. A second failure after a second reset points below the USB layer — move to the decision table.

  2. Eye safety: the infrared pattern projector can fire the moment firmware loads. Keep your eyes out of its output cone while you cycle the port.

Stop it coming back

Close on every exit path. The shape, in pseudo-code — substitute your SDK's real names:

device = None                     # illustrative
try:
    device = open_depth_camera()  # illustrative: your library's open call
    run_pipeline(device)          # illustrative: your capture loop
finally:
    if device is not None:
        device.close()            # returns the camera to pre-boot state
time.sleep(1.0)                   # let the kernel finish releasing it

The finally block is the whole trick: cleanup that survives Ctrl+C removes most wedges at the source. kill -9 still skips it — nothing survives SIGKILL — which is why the port reset stays in the toolbox. A camera that instead times out on reopen usually needs its streams stopped before the close: stop acquisition before you close covers that sibling failure.

Pin the port awake. One udev rule disables autosuspend for the camera's vendor:

ACTION=="add", ATTR{idVendor}=="03e7", ATTR{power/control}="on"

Save it as a .rules file under /etc/udev/rules.d/, then load it:

sudo udevadm control --reload-rules && sudo udevadm trigger

power/control set to on keeps the interface active between runs, removing the resume path that breaks the next boot. The permission side of udev — the mode and group rules that stop "permission denied" on the same device — is a separate file: udev rules for USB cameras on Linux covers it.

Make the supervisor self-healing. One retry after a reset turns a crash into a five-second blip:

resets_left = 1                        # illustrative
while True:
    try:
        device = open_depth_camera()   # illustrative
        break
    except RuntimeError:               # the failed-to-boot raise lands here
        if resets_left == 0:
            raise
        resets_left -= 1
        reset_usb_port("03e7", "2485") # illustrative: runs usb_modeswitch -R
        time.sleep(1.5)

The downtime arithmetic

Typical timings on a Linux host with the camera on a root-hub port:

Path Components Total
Port reset 1.5 s re-enumeration + 3.0 s firmware boot + 0.5 s to first depth frame 5.0 s
Host reboot 90 s OS boot + 30 s application start + 30 s camera power-up and open 150 s
reset_path = 1.5 s + 3.0 s + 0.5 s = 5.0 s reboot_path = 90 s + 30 s + 30 s = 150 s speed_up = 150 / 5 = 30

The port reset returns the camera to service about thirty times faster. Your OS boot time moves the second row; the first row is set by the device's firmware load and barely moves.

Which fix, when

What you observe Cause Action
lsusb lists the camera; open raises X_LINK_UNBOOTED wedged half-booted state port reset now; add the finally close
Failure appears only after idle minutes autosuspend power/control=on udev rule
dmesg shows -71, or the device vanishes between runs link or power cable and port first
Camera always enumerates high-speed USB 3 pairs not training shielded USB 3 cable, root-hub port
Survives two hosts with clean closes the device replacement path

When the port reset is the wrong answer

The reset fixes the handoff. It does not fix a link that drops packets or a camera that has failed, and using it to mask either one only moves the outage.

Link layer. The USB 3 spec allows 3 m of passive copper at 5 Gbit/s; longer runs need an active cable, and machine-mounted runs want a flex rating. For a mounted camera, a drag-chain rated 3 m USB3.0 cable such as the LS-CBL-0219 fits both limits:

Cables3 m USB3.0 camera cable, high-flex (drag chain) (LS-CBL-0219)LS-CBL-0219$62.00View partBuild a system with it

More lengths and connector types sit in the cables range. Forcing the camera to USB 2 is a fair bring-up test at 480 Mbit/s, but production depth streaming wants the full 5 Gbit/s link back.

Device layer. If the wedge survives two hosts, two cables, root-hub ports and clean closes, the camera itself has failed — stop resetting and replace it. A ready-to-run option is the MV-DT01WMU ToF camera; for an embedded build, the LS-BCM-0043 binocular module streams stereo over USB3. Compare both directly:

3D sensorsHikrobot MV-DT01WMU ToF sensing cameraMV-DT01WMU
Type
Depth / ToF camera
Price on requestView and quote
Board-level camerasBinocular camera / module, 1.3 MP, USB3, Colour/Mono, 1280 x 1024 @ 123FPS resolution (LS-BCM-0043)LS-BCM-0043
Sensor format
1/2"
Lens mount
M12
$179.00View part

The wider selection sits in the 3D sensors and board-level cameras ranges.

The power-loss cousin. A depth camera that comes up with no frames after a mains dip, rather than after a close, is the neighbouring failure: the software reset fix after a depth camera power loss.

Checklist before you call it fixed

  • kill -9 the capture process, then reopen: one reset recovers it, ten cycles in a row. The kill test is the acceptance criterion, because SIGKILL is the worst exit your application can take.
  • finally close on every exit path, then a 1 s pause before the next open. It costs nothing to add, and it removes the source of the wedge.
  • power/control reads on for the camera's vendor ID after a replug. That proves the udev rule is live, not just written.
  • Camera on a root-hub USB 3 port, passive cable 3 m or shorter, no hub in between. Every hub adds another link that can train badly.
  • dmesg clean of -71 across a full shift. Repeated -71 means the reset is masking a cable or power problem.

If the failure follows the camera across hosts, contact us about a replacement, or compare 3D cameras for the next unit. More depth-camera fixes are collected on the 3D vision topic page.

Questions

Does X_LINK_UNBOOTED mean the depth camera is broken?

No. The camera still enumerates on the bus — lsusb lists it — so power and the USB link are up; only the firmware boot handoff refused. A single port reset returns it to pre-boot state and the next open boots it normally. Treat the camera as suspect only when two resets on two different hosts both fail, or when lsusb stops listing the device between runs.

Why does unplugging the camera sometimes not fix it?

A replug only helps when it cuts power to the device. On many boards VBUS stays live on the port, so the camera never loses its wedged state and re-enumerates right back into it. The unbind/bind path forces the driver detach regardless of power, which is why it recovers cases a replug does not. It also saves the walk to the machine on a production line.

Does resetting one USB port disturb other cameras on the same host?

No, when the cameras hang off separate root-hub ports. The reset targets one device by vendor and product ID, and the unbind/bind path targets one bus-port address, so siblings keep streaming. If your cameras share an external hub, resetting the hub's own upstream port would re-enumerate everything downstream — address the camera, not the hub, and the others stay untouched.

What does setting power/control to on actually cost?

It tells the kernel to keep that device's interface in the active state instead of autosuspending it between runs, which removes the resume path that breaks the next boot. The cost is a small rise in idle power draw on one USB device. On a mains-powered inspection station that trade is almost always right; on a battery-powered rig, keep the rule and accept a slightly shorter runtime.

Do I lose calibration or device settings after a port reset?

No. The reset only forces re-enumeration of the USB link — nothing is written to the camera. Stored calibration stays where the maker put it, and the next normal boot reloads the runtime firmware exactly as a fresh start would. You lose nothing but the wedged state itself, which is the point.