Failed to claim USB interface: one client owns a USB3 Vision camera

Your USB3 Vision camera passes discovery — it appears in the device list, and lsusb sees it on the bus — but the open dies with a failed to claim USB interface message, followed by a spray of assertion errors. One refusal, three causes, all fixable in minutes. This walkthrough is for engineers bringing a USB3 Vision area scan camera up on Linux, through a GenICam tool such as arv-tool, the Aravis library, or your own libusb code. You will separate a busy interface from a permission fault with one sudo run, write the udev rule that keeps the fix in place, and budget the bandwidth that decides how many cameras one host carries.

What a failed claim actually means

A USB3 Vision camera exposes at least two USB interfaces: a control interface that carries the GenICam register traffic, and a data interface that carries the image stream. Opening the camera means claiming both through libusb, and a claim is exclusive. Once one process owns an interface, the kernel refuses every further claim with a busy status, and the library surfaces that refusal as failed to claim USB interface.

Discovery is not ownership. Listing a device — what lsusb does, and what arv-tool does before it opens — reads the device descriptor, which claims nothing and needs no special permission. A camera that lists cleanly is therefore proven alive at the cable, port and link, and completely unproven at ownership. If lsusb lists nothing at all, you have a different fault; see the USB camera that died electrically case instead.

The assertion errors after the claim failure are fallout, not a second fault. The library tried to destroy a camera object it never successfully created, so every later call complains about an invalid object. Fix the claim and the whole log goes quiet.

The causes, most likely first

1. Another live process holds the camera. A vendor viewer left open, a colleague's session, an acquisition script still running in a terminal — whoever claimed first owns it until it exits. This is the same one-client rule behind the GigE exclusive control fault and behind a camera that works in the vendor tool but not in ROS.
2. Your user lacks write access. A non-root user without a matching udev rule cannot write to the camera's device node, so the claim is denied and reported as a failed claim even though nobody holds anything. The tell: the identical open succeeds under sudo.
3. A kernel driver claimed an interface first. Some cameras enumerate as composite USB devices, and at plug-in the kernel can bind a driver such as usbhid to one interface before your software asks. dmesg records the binding the moment it happens.
4. Parallel opens race inside the library. Starting two USB3 cameras from two threads at once can fail on both, with free devices and clean permissions: older Aravis releases had a thread-safety defect on their shared USB3 open path. Current releases handle it, and serializing your opens avoids it on any version.

The same refusal on 3D depth cameras has its own walkthrough if that is your device class. The claim rules come from the USB3 Vision standard rather than from the camera model, which is why the two USB3 area scan cameras below fail and recover in exactly the same way.

Test each cause in five minutes

1. Read the IDs. Run lsusb and note the camera's idVendor and idProduct, two four-digit hex values separated by a colon. You need the pair for the udev rule, and it identifies this exact camera in every later log.
2. Clear the field. Close every viewer and acquisition program, then list processes and stop anything still holding a session — a hung script in another terminal counts. Re-run the open. Most claim errors end here.
3. Try root once. Run the identical open under sudo. Success moves the fault to permissions, so go to step 5. Failure with root means a live owner, so repeat step 2 more aggressively.
4. Replug and race. Unplug the camera, plug it back, and open immediately, before any GUI tool starts. If it works now and fails minutes later, something grabs the camera at plug-in: check the dmesg timestamps against the plug event and disable that auto-start.
5. Apply the udev rule from the next section, reload udev or replug, and open as your normal user — no sudo again.

A different fault wears a similar costume: a camera that enumerates as USB 2.0 gives thin frames and timeouts, not claim errors. That repair lives in the USB 2.0 enumeration fix, and the usual culprit is the cable. On a moving rig, a shielded, drag-chain-rated USB 3.0 camera cable such as the 3 m LS-CBL-0219 removes that variable.

Fix permissions with a udev rule

Sudo is a diagnosis, not a fix. The durable repair is a udev rule that grants your user write access every time the camera plugs in.

1. Take the idVendor and idProduct values from lsusb, four hex digits each.
2. Create a file in /etc/udev/rules.d/ with a high ordering prefix — anything.rules with a 99- prefix keeps it late in the evaluation order. Give it one line that matches the device by ATTRS{idVendor} and ATTRS{idProduct} and sets MODE="0666", with the two values from step 1 in the match keys.
3. Apply it: udevadm control --reload-rules, then udevadm trigger — or simply unplug and replug the camera.
4. Verify by opening as your normal user. If it still fails without sudo but works with it, re-check the two hex values: one wrong digit matches nothing and fails silently.

The open-source Aravis project documents exactly this permission setup for USB3 Vision cameras; it is the standard Linux answer, not a workaround of any kind. Your own code needs nothing special either: it opens the same device nodes through libusb, and with the rule in place the claim succeeds under your own login.

Worked example: one 12 MP, 30 fps USB3 camera on one port

Ownership and bandwidth meet at the same question — how many clients and cameras a port carries. Take the LS-CMR-0166 as the case: a 12 MP USB3 camera streaming 4000 × 3000 pixels at 30 fps.

As printed in the product data sheet.

• Frame size and rate: 4000 × 3000 at 30 fps, from the camera specification in the table above.
• Pixel format: Mono 8, one byte per pixel, the usual full-rate choice for a mono sensor.
• Link budget: USB 3.0 runs a 5 Gbit/s line rate; 8b/10b encoding leaves 4 Gbit/s = 500 MB/s of raw data rate, and packet overhead leaves roughly 400 MB/s of payload for a USB3 Vision stream.

The rule in words: payload bandwidth equals pixels per second times bytes per pixel, and a stream fits on one USB 3.0 connection only under that controller's payload ceiling.

Arithmetic: 4,000 × 3,000 = 12,000,000 pixels per frame, and 12,000,000 × 30 fps = 360,000,000 pixels per second. Mono 8 carries one byte per pixel, so the stream is 360 MB/s — under the roughly 400 MB/s ceiling, with about 40 MB/s (10 %) of headroom. Mono 10 packs ten bits, about 1.25 bytes per pixel: 360,000,000 × 1.25 = 450 MB/s, which is 50 MB/s over the ceiling, so full rate is out. The ceiling allows 400 MB/s ÷ 15,000,000 pixels per frame = 26.7 frames per second, call it 26 fps.

Decision: on one port this camera runs 4000 × 3000 at 30 fps in Mono 8, or about 26 fps in Mono 10. Two such cameras together demand 720 MB/s, more than the shared 5 Gbit/s link of one controller carries, so give the second camera its own host controller or cut the frame rates the arithmetic allows. And no second client shares the camera regardless of bandwidth: the claim is exclusive by design, so the busy error while your acquisition runs is the standard working, not a defect. If two cameras both open but frames drop, move on to the host USB buffer fix.

When the usual fix is not enough

Openings from several threads. If every camera opens cleanly alone but two fail when started together from threads, serialize the first open per camera behind a mutex and upgrade to a current release of your GenICam library. The USB3 open path in older Aravis releases was not thread-safe around its shared interface object.

A kernel driver got there first. dmesg showing usbhid bound at plug-in means a kernel driver took an interface before your process ran. Current libraries detach kernel drivers automatically when they claim; if yours does not, enable libusb's auto-detach — the documented call is libusb_set_auto_detach_kernel_driver — before your first claim, or unbind the driver from the interface once by hand to confirm the diagnosis.

An auto-starting viewer. Some vendor packages register an autostart entry or a background service that opens the camera at login or at plug-in. Your process then loses a race you did not know you were running. Remove the autostart entry or configure the tool to stay closed.

Two identical cameras. Sort out which camera is which by USB port path rather than by name; the identical USB cameras guide shows how to pin each camera to its socket so the udev rules stay per-device.

Keep it fixed

• Treat a busy claim as information: someone owns the camera, so ask who before touching drivers or cables.
• Close vendor viewers before your own runs — one client at a time is the rule, not a limitation of your code.
• Put the udev rule on every Linux host the camera touches, before the first run, not after the first failure.
• Release the camera in a cleanup path — a finally block or a signal handler — so an interrupted run lets go cleanly.
• Budget bandwidth before adding a camera: run the width × height × fps × bytes-per-pixel product per camera and compare it with the roughly 400 MB/s payload of one USB 3.0 controller.
• Log claim failures with their status code, so the next reader sees busy versus denied instead of assertion spam.

Where to go next

If you are specifying hardware for a USB3 station, browse the USB3 area scan cameras — the camera finder filters by interface, resolution and shutter — and match cable length and flex rating under camera cables. The configurator walks camera, lens, light and controller in order, and the systems topic page gathers the rest of the acquisition faults. If a claim error survives every step above, contact the applications team with your lsusb line and the exact open log. If the one-client rule does not fit your architecture at all, the interface comparison from Camera Link to USB3 shows where multi-client access actually exists.