GigE camera not online in ROS: fix the three stacked causes

Your ROS 2 driver node starts, reports startup failed, and then prints camera is not online on a retry timer. The same configuration worked on the previous ROS release, so the camera hardware is probably fine — the software layer beneath it moved. Three causes stack in practice: a parameter YAML path that starts with '~' and never opens, a missing udev group membership after an SDK or OS reinstall, and a second process holding the camera. This guide gives you the log lines that separate the three, the fix for each, and the order to work through them so you change one thing at a time.

Read the first error, not the looping warning

The warning loop is the symptom; the diagnosis sits higher in the same log. In this failure the sequence is consistent: the node reads your parameters, echoes the definitions path, fails to open that file, aborts camera startup, and then loops a warning every 5 seconds — while still announcing that the node started. A running process is not a connected camera.

Decision rule: if startup failed! appears before the first warning, start at Cause 1. If the parameters load cleanly and the warning still loops, go to Cause 2 or Cause 3. When all three causes are cleared and the warning persists, the fault is on the wire, not in the launch file.

Cause 1: the tilde in the YAML path

A launch parameter reaches the node as a plain string. Shell expansion is what turns '~' into your home directory, and no shell ever sees the parameter, so the driver tries to open a file literally named ~/... and fails. Startup aborts before the camera is touched, and the warning loop begins.

1. Find the launch file or parameter block that sets the driver's parameter definitions path.
2. Replace the leading '~' with the absolute path, for example /home/youruser/cam_ws/src/your_pkg/config/camera.yaml.
3. Relaunch and read the echoed parameter definitions file: line — it must start with /home/, not with ~.
4. Confirm the bad file error is gone before changing anything else.

When the log moves on to a calibration or streaming line, this cause is cleared. One line that looks like a failure is not: using default calibration URL means your settings loaded and only the calibration file is missing, which never blocks the connection. Configuration carried across a ROS upgrade often needs more than a path fix, because parameter names get renamed between releases — ROS camera launch parameter not supported: fix renamed settings walks through that migration.

Cause 2: the udev group your user never joined

With the path fixed, the driver loads the vendor library and enumerates cameras. A rebuilt OS install can leave you with the library but no device access: the ROS driver packages ship their own copy of the vendor library, while the udev rules and the device group come from the camera SDK, and those did not survive the reinstall. Enumeration then finds nothing, or works only under sudo.

The test is one step: run the SDK's example capture program as your normal user, before starting any ROS node. If it lists cameras and grabs frames, the entire layer below ROS is proven and you can skip to Cause 3. If it needs sudo to see anything, device access is the fault.

1. Run the SDK installer's udev setup step, which writes its rules under /etc/udev/rules.d/, creates a device group — the installer prints its name — and adds your user to it.
2. If a later installer step fails, check the outcome anyway: the rules and the group are written early, and the failing step is often unrelated to camera access. Confirm the rules file and the group exist; add your user to the group with your distribution's user-management tool if needed.
3. Log out and back in so the membership applies — a reboot is the certain version.

Verify in a new terminal: groups must print the camera group, and the example tool must list and stream without sudo. Only then start the ROS driver. USB cameras show the same class of fault as missing access to a /dev/video* node; Linux camera device permissions: video and media node checks covers those checks, while a GigE camera is reached through the SDK's rules instead.

Cause 3: another process holds the camera

A GigE camera serves one client at a time. While a viewer window, a stray driver copy or an autostart service holds the stream, your node cannot open the device and reports the camera as unreachable. During debugging, the most common holder is your own earlier process.

1. List what is running: ros2 node list for ROS nodes, and a normal process listing for duplicate driver copies.
2. Close every camera viewer and stop every node except one driver instance.
3. Relaunch the driver and watch the first connection attempt.

If nothing can open the camera even after this — for example after a crashed run — the device needs a clean release, and Release a camera after a crash on Linux: GigE restart fix gives the reset sequence. The lock behavior itself, why a second tool cannot open a held camera, is explained in GigE camera open fails in a second tool: exclusive control.

Cleared all three? Then it is the wire

Now the parameters load, the group is right, and no other process holds the camera — but the warning keeps looping. The camera is not answering on the network, so work upward from the physical layer. Keep the checks in GigE terms: USB port and bus-speed advice does not apply here, because a GigE camera's bus is the Ethernet link itself.

• Link LEDs. A dark LED on either end means power or cable first: check the PoE budget on that switch port or the camera's auxiliary supply, then reseat the connector.
• Discovery order. A driver that enumerates before the camera has power and a link finds nothing; GigE camera not discovered on startup: fix the boot order gives the power-up sequence.
• Subnet and firewall. A camera on a different subnet than the host is invisible to discovery; Access GigE cameras from another subnet without direct cabling shows how to reach it without rewiring.

The intermittent version — online at launch, offline after minutes or after the robot moves — is usually mechanical: a plain patch lead that walks out of its jack. Fix that in hardware. The LS-CBL-0117 is a 15 m camera data cable with an RJ45 plug on a locking stud for fixed runs, and the LS-CBL-0199 is a 3 m high-flex GigE cable with screw locks for drag chains; both sit in the camera data cables category, and the accessories finder filters them by length and connector.

Prevention: five checks before the next launch

• Absolute paths for every file parameter in the launch configuration — a moved or rebuilt workspace stops breaking the open.
• udev setup and group membership redone after every SDK or OS reinstall, followed by a logout — distribution upgrades are when this fault returns.
• The SDK example tool streams before the ROS node starts — the layer beneath ROS is proven first.
• One owner per camera serial — viewers closed, a single driver copy, no autostart surprises.
• The first ERROR read on every failure — the log names the stage that never ran.

The remaining connection and access fixes are collected on the systems guides topic page.

Choosing the camera when you rebuild the station

The same order applies to a fresh workstation: absolute paths, group membership, one owner, then the wire. If you are picking the camera itself, a GigE model with a global shutter suits conveyor and robot-cell work; the MV-CU020-90GC is a 2.5 MP GigE camera with a global shutter, a 1/1.7" sensor and a C-mount.

Browse the area scan cameras category or the camera finder, and let the camera step of the configurator match the lens and cable to it. If the warning still loops after all three fixes, send us the complete log from launch to the last warning through the contact page — the first ERROR line names the stage that never ran.