USB3 Vision camera works as root only: fix the udev rule

A USB3 Vision camera that enumerates, prints its product string and serial, and then dies with Failed to claim USB interface is almost never broken. When the same camera runs perfectly every time under root and only sometimes as your normal user, the fault is the Linux device node's permissions, not the camera, the cable or the GenICam stack. This guide walks the diagnosis for any USB3 Vision camera — area scan, board-level or code reader — on any modern Linux distribution: how to read the error, the udev rule that fixes it, the group and re-login step people forget, and the three failures that look like it but are not (a second client holding the interface, the 16 MB usbfs transfer cap, and a link negotiating down to USB 2.0).

Symptom: discovery works, the claim fails

The log says the library got almost all the way. It prints the vendor, the product string and the serial, finds a control endpoint on interface 0 and a data endpoint on interface 2, and counts the device on the bus — in the failing log, one USB3 Vision device among seven USB devices. Descriptor parsing, endpoint selection and USB3 Vision identification all worked. The next step is the one that fails: claiming those interfaces so the kernel guarantees exclusive access. The library reports the claim failure, and a GLib critical about g_object_unref follows it. That critical is the library freeing a half-built device object after the failure — an effect, never a cause. Read past it.

The failure sits below every vendor stack and every sensor type. It hits area scan cameras such as the LS-CMR-0166, a 12 MP USB3 area scan camera, board-level cameras built into machines, and code readers alike. All of them open a node under /dev/bus/usb/ and ask the kernel for the interface; the kernel answers before any GenICam XML is fetched from the camera.

Why root works every time

USB device nodes are created root-owned when the camera enumerates — on most distributions root:root with mode 0664, on stricter setups 0600. Root holds the capability that overrides file permission bits, so the identical claim succeeds under sudo every time. Your account instead needs write permission on that node, because a camera library opens it read-write and issues the claim ioctl on that open file.

Decode the mode and you can predict the error. In 0664 the owner gets 6 = 4 (read) + 2 (write), the group gets 6, everyone else gets 4 (read only). The group is root, your user is not in it, so the write bit never reaches you. Opening the node read-write returns errno 13 (EACCES, permission denied), libusb reports code -3, access denied, and the library above it prints the claim failure. One default, one error, every time.

If the camera does not appear on the bus at all, that is the sibling fault: USB3 Vision camera not detected on Linux: fix udev permissions.

Prove it in three commands

1. lsusb prints one line per device in the form Bus BBB Device DDD: ID VID:PID Vendor Product. The two four-hex-digit values after ID are the match keys for your rule, and the bus and device numbers give the node: bus 001, device 007 means /dev/bus/usb/001/007.
2. ls -l /dev/bus/usb/001/007 prints the owner, group and mode. If your group has no w, the claim cannot succeed as that user — stop debugging the library.
3. udevadm info -a -n /dev/bus/usb/001/007 walks the device and its parents; the ATTRS{idVendor}, ATTRS{idProduct} and ATTRS{serial} lines are the values your rule can match.

The fix: one rule, one group, one re-login

1. Create a group for camera users: sudo groupadd vision.
2. Add yourself: sudo usermod -aG vision $USER. Group membership is read at login, so open a fresh session before you test.
3. Create /etc/udev/rules.d/70-usb3vision.rules with one line per camera model:

SUBSYSTEM=="usb", ACTION=="add", ATTRS{idVendor}=="VID", ATTRS{idProduct}=="PID", MODE="0664", GROUP="vision"

4. Replace VID and PID with the two values from your lsusb line; every other token is literal. ATTRS rather than ATTR, because the node inherits these attributes from the parent usb_device. To scope one physical unit, match ATTRS{serial}=="SERIAL" instead, one line per serial.
5. Load the rule: sudo udevadm control --reload-rules.
6. Replug the camera. Rules with ACTION=="add" fire at add events, so a replug is the honest test; sudo udevadm trigger re-runs rules for already-connected devices when the machine is sealed.
7. Confirm the node changed: ls -l /dev/bus/usb/001/007 should now print crw-rw-r-- root vision — group read and write, 6 = 4 + 2. Then run your camera tool as the normal user.

For the general form of these rules across camera types, read Udev rules for USB cameras on Linux: fix permission denied. Board-level modules follow the same rule — the MV-CB060-10UM-B, a 6 MP USB3 board-level camera, is just another node on the bus — but when one streams through a bridge board, match the pair first: Board-level camera and USB3 bridge board: match before you stream.

When the rule is right and it still fails

Another client already holds the interface

Now the error wording changes: errno 16 (EBUSY), libusb code -6, Device or resource busy. The kernel allows exactly one claimer per USB interface, and root cannot override a busy claim — sudo fails the same way. That is your discriminator: an access error follows permissions, a busy error follows ownership. Find the holder with sudo lsof /dev/bus/usb/001/007; the usual holders are a vendor tool left open, a discovery daemon, or a crashed instance whose lock outlived it.

Start with Failed to claim USB interface: one client owns a USB3 Vision camera for the single-camera case, Two cameras interface claim conflict: diagnose USB access for the multi-camera bench, and Camera works in the vendor tool but not in ROS: one client at a time when the other client is the vendor's own viewer. A stale lock after a crash is covered in Stale /dev/shm device lock when a second user opens the camera. The network cousin of this error is GigE camera open fails in a second tool: exclusive control.

The claim succeeds but frames starve: the usbfs memory cap

Read the budget: cat /sys/module/usbcore/parameters/usbfs_memory_mb. The kernel default is 16, meaning 16 MB of in-flight USB transfers for the whole usbfs path, which is the path every user-space vision library takes. One 4000 × 3000 mono frame is 4000 × 3000 × 1 byte = 12 MB; two queued frames are 24 MB, past the budget, and submissions fail with errno 12 (ENOMEM) although the claim was clean.

Fix it now with echo 1000 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb, and at boot by adding usbcore.usbfs_memory_mb=1000 to the kernel command line; the sysfs write alone resets at the next reboot. For what several cameras on one controller do to that budget, read Acquire from multiple USB cameras: bandwidth and sync, and for embedded hosts 3D depth camera on an ARM SBC: USB3 bandwidth and CPU budget.

The link fell back to USB 2.0

lsusb -t prints the negotiated speed per device: 5000M for SuperSpeed, 480M for USB 2.0. A camera on 480 Mbit/s enumerates and claims without a complaint and then starves: 480 Mbit/s is 60 MB/s on the wire (480 ÷ 8), roughly 40 MB/s in practice — about three 12 MB frames per second. Reseat both connectors along the run, remove any bus-powered hub, swap to another port, and replace a suspect cable with one rated for the job from the camera cables range, such as the LS-CBL-0219, a 3 m USB3.0 camera cable built for drag-chain use.

The full diagnosis for the fallback is Camera enumerates as USB 2.0 on a USB 3.0 port: fix the link; on embedded compute modules, USB3 cameras falling back to USB2 speed covers the port-side causes. When the link is healthy but acquisition still stops, see USB3 Vision camera start_acquisition fails on Linux: fix the link and USB3 Vision device response timeout: cap the bulk-transfer wait.

The GenApi schema warnings are a red herring

The same console often carries lines like Invalid xsd file ... GenApiSchema_Version_1_0.xsd, repeated for the 1_1 schema. These come from GenApi validation: the library checks the camera's register-layout XML against the GenICam schema files, and on the installation in question those files are missing from the path printed in the warning. The library skips validation and carries on. Nothing in that code path touches USB, and the interface claim is granted or refused before the XML is fetched from the camera.

Two faults, two fixes. Install the schema files at the path the warning names if you need validated XML, and the lines go quiet — they will not change the claim outcome. Chase the claim first, the warnings afterwards.

Match the fix to the error you actually see

Before you blame the camera

• The rule file under /etc/udev/rules.d matches the IDs your lsusb line prints today; a replacement camera brings a new serial if you match by serial.
• ls -l on the node shows your group with write at the moment of failure, not after a replug.
• id -nG in the exact shell that runs the camera lists the group; shells inherit groups at launch.
• One client per camera: vendor viewers, daemons and crashed processes either release the claim or keep it.
• usbfs_memory_mb reads 1000 on production machines, set from the kernel command line so it survives reboots.
• The camera sits on a locking USB3 cable with no bus-powered hub between it and the port.

With permissions settled, pick the hardware around them: the camera finder filters by interface and mount, or start at the camera step of the vision system configurator. For fleet installs that need the rules scripted and rolled out, reach us through the contact page.