A demo that starts, prints a healthy log and never opens a window is one of the most common first-day faults on a Linux vision host, and the camera is almost never at fault. The capture half of the program talks to the device; the window half talks to the desktop, and the desktop is where it dies. You can separate the two in five minutes, from the console alone. Here are the signature log lines, the environment variable that fixes the most common case on a GNOME Wayland session, a headless capture proof you can run before any GUI exists, and a bandwidth check that catches a USB link quietly running at 480 Mbps. Most of it works over SSH, with no monitor attached.
The console tells you which half failed
Start the demo with a terminal in front of you and read it before judging the window. Capture code logs enumeration, firmware loads and stream starts. GUI code logs warnings about platforms, sessions and graphics devices. A healthy run prints capture lines and then a window; a broken run prints one of two signatures.
The first signature is the Wayland warning:
Warning: Ignoring XDG_SESSION_TYPE=wayland on Gnome. Use QT_QPA_PLATFORM=wayland to run on Wayland anyway.
That line means Qt detected the Wayland session but launched its X11 plugin anyway. The second signature is a renderer panic:
[2024-08-29T02:30:16Z WARN wgpu_core::instance] Missing downlevel flags: DownlevelFlags(FULL_DRAW_INDEX_UINT32)
followed by a panic saying the device does not support the required features. Neither signature contains a capture word, which is the point: both failures live in the display half. If the console shows neither line and the app exits silently, the device half failed first, and the enumeration check below is your next step.
Four causes, most likely first
When a demo runs but no window appears, rank the causes in this order.
- Qt on the wrong platform plugin. A Qt-based viewer defaults to its X11 plugin. On a GNOME Wayland session, especially over VNC, that path can have no usable display, so the window never maps. The console shows the XDG_SESSION_TYPE warning. This is the most common cause by a wide margin.
- Renderer below the GPU floor. The viewer draws through WebGPU. On a headless host, a virtual VNC display or a small board with software rendering, the adapter lacks the features the renderer requires, and the draw thread panics while capture keeps logging.
- Device open fails before any GUI code runs. No enumeration (cable or power), no permission (user outside the device group, udev rules not installed) or, for GigE, a subnet mismatch. The app exits quietly or prints an error you scrolled past.
- The link cannot carry the stream. A USB camera that enumerated at high speed (480 Mbps) or browned out on an unpowered hub starts the stream and stalls; the window may appear and freeze, or the app exits while starting the stream. This fault shows up most on USB3 board-level cameras and depth units carried between benches.
| Console signature | Likely cause | First fix |
|---|---|---|
| XDG_SESSION_TYPE=wayland warning | Qt running its X11 plugin in a Wayland session | QT_QPA_PLATFORM=wayland, fallback xcb |
| Missing downlevel flags, then a panic | GPU below the renderer's feature floor | Headless proof, then a GPU-backed session |
| No device in lsusb or the SDK list | Enumeration or permission | Cable and power first, then group and udev |
| new high-speed USB device in dmesg | Link fell back to 480 Mbps | SuperSpeed port, short cable, powered hub |
| Repeated connect and disconnect in dmesg | Power brown-out | Powered hub or external supply |
Test in this order; each check below takes about a minute.
Set the Qt platform on purpose
If XDG_SESSION_TYPE prints wayland and the console shows the warning, fix the variable before touching anything else. Do it in the same shell that will start the demo:
echo $XDG_SESSION_TYPE # expect: wayland
export QT_QPA_PLATFORM=wayland
printenv QT_QPA_PLATFORM # must print, here, before you launch
./run-the-demo
Start with QT_QPA_PLATFORM=wayland. If the window still fails, fall back to the X11 plugin, which some vendor GUIs are tested against exclusively:
export QT_QPA_PLATFORM=xcb
Under GNOME Wayland, X11 applications run through XWayland, so the xcb plugin still displays as long as XWayland itself is healthy.
The variable only reaches processes started from that shell, which is why an export so often appears to do nothing. A new terminal knows nothing about it. sudo strips the environment unless you pass sudo -E. A desktop icon or a service starts the demo from a different environment entirely. Set the variable inside the launcher instead:
printenv QT_QPA_PLATFORM >/dev/null || export QT_QPA_PLATFORM=wayland
Prove capture with no GUI at all
Fix the display half only after the device half is proven, and the proof needs no window. Open a second terminal and leave it running:
sudo dmesg -w
Replug the camera. Healthy enumeration on a working port prints lines like new high-speed USB device number 3 using xhci_hcd, followed by the idVendor and idProduct strings; on a SuperSpeed-capable port, the same line reads SuperSpeed. A device whose product string changes when the demo starts is loading firmware over USB, which is normal for this class of camera. lsusb should list the device with its vendor:product ID.
Then close the loop with frames rather than logs. For a UVC/V4L2 camera, ten lines with OpenCV are enough; a vendor-SDK camera has an equivalent grab call with the same idea:
import cv2
cap = cv2.VideoCapture(0) # index 0 = first V4L2 device
n = 0 # frames grabbed, starts at 0
for _ in range(150): # about 5 s at 30 fps
ok, frame = cap.read() # ok: bool; frame: image array or None
if ok:
n += 1
print(n, 'frames grabbed') # healthy run: about 150
Permission errors point at access, not at the camera: check groups for membership in the video group, which owns V4L2 device nodes, and install the udev rules that ship with the SDK. The deeper isolation of capture versus rendering is in Camera window opens but no video: isolate capture from rendering. If the device never appears at all, start with USB camera not detected: check the cable before you swap hardware and Camera shows in lsusb but no video device: check the USB class.
Depth and profiler units gain the most from this proof, because they boot several sensors at once; the vendor's simple RGB capture example beats the full demo for a first bring-up. The 3D sensors category is where those cameras live.
Worked example: 4000 × 3000 at 30 fps over a high-speed link
The inputs: the camera mode is the printed mode of the LS-CMR-0166, a 12 MP USB3 area scan camera listing 4000 × 3000 at 30 fps. The dmesg line comes from a real bring-up in which the camera enumerated at high speed. The bit depth is an assumption: 8 bits per pixel, uncompressed, the common preview format.
The rule in words: an uncompressed stream needs width times height times bit depth times frame rate of link bandwidth, and the USB standard in use caps what the link can carry.
The payload figures are typical measured values after protocol overhead; 480 Mbps and 5 Gbps are the line rates the USB standards define.
The arithmetic, step by step. 4000 × 3000 = 12,000,000 pixels per frame. At 8 bits each, one frame is 96,000,000 bits, which is 12 MB. At 30 fps the stream needs 12 MB × 30 = 360 MB/s, or 2,880 Mbps. A high-speed link carries about 50 MB/s, so the mode runs 360 ÷ 50 = 7.2 times over budget; even the raw 480 Mbps line rate, 60 MB/s, falls short by a factor of six. On a healthy SuperSpeed link, the same 360 MB/s fits inside about 400 MB/s with roughly 10% headroom.
The decision: any continuous stream above about 400 Mbps needs a SuperSpeed link. If dmesg says high speed for a camera whose mode needs more than that, the cable, port or hub is the fault. Replace the path, confirm SuperSpeed in dmesg, and only then judge the GUI. A window that opens and then freezes on this signature is a bandwidth fault, not a Wayland fault.
The mode worked here is the printed mode of the LS-CMR-0166, and the same budget check applies to any USB3 camera on a Linux host.
- Sensor format
- 1/1.7"
- Interface
- USB3
- Sensor format
- 1/1.8"
- Interface
- USB3
- Type
- Depth / ToF camera
Bandwidth is only half of the USB budget. A USB 3.0 port supplies up to 5 V × 0.9 A = 4.5 W, and an unpowered hub divides that among its downstream devices. A bus-powered camera that dips below its draw browns out, and dmesg shows a connect and disconnect loop. Give the camera a powered hub or its own supply and the loop stops. The dock-and-hub failure pattern, with its fixes, is in Depth camera shows a black window: fix the USB dock and hub path.
The downlevel-flags panic: the GUI needs a better GPU
The fastest discriminator costs nothing: plug in a monitor. If the window appears on a directly attached display but not through VNC, the virtual display is the gap, and the camera is fine.
When the console shows Missing downlevel flags, the renderer has already told you the answer. WebGPU implementations such as wgpu enforce a feature floor before they create a device; FULL_DRAW_INDEX_UINT32, the ability to address draws with 32-bit indices, is part of that baseline. Adapters that fail it cannot create a device, so the process panics while capture threads keep logging. Three host classes hit this: a headless server with no usable GPU, a VNC session on a virtual or software display, and small ARM boards whose graphics drivers sit below the floor.
Confirm the display class if glxinfo is installed:
glxinfo -B | grep -i renderer # llvmpipe means software rendering
llvmpipe means the session has no hardware acceleration, and every GPU-dependent viewer will behave the same way.
Then take the exits in order. First, skip the window: the headless proof above validates the camera, and QT_QPA_PLATFORM=offscreen lets some Qt tools start with no display at all. Second, run the GUI where acceleration exists: the real desktop on :0 shared with x11vnc, rather than a virtual VNC display. Third, move the viewing job to a host with a supported GPU; for a unit that lives at the line, that is the job of industrial mini PCs with real graphics support.
The same GPU gap stalls other render paths, which Stereo depth node won't start: verify GPU runtime libraries first covers for ROS-style stacks. If the video should end up on a panel rather than a desk monitor, Remote client no video? Put the display window on the front panel shows the client side. For a host meant to run headless permanently, Headless Linux vision server install: skip the GUI, keep the X libs is the matching set-up.
The decision: on a GPU-less host, treat the demo window as optional. Automate capture without it and give a human a GPU-backed session only when someone must watch the image.
GigE cameras: same fixes, different enumeration
Everything from the platform variable to the GPU floor applies unchanged to GigE area scan cameras, because those failures belong to the host. Enumeration is where the paths split: a network camera never appears in lsusb. Use the SDK's device enumerator, confirm that the camera and the network interface share a subnet, and expect a clear enumeration error long before any GUI code runs. The network half is walked through in 3D camera not pingable on a Linux controller: fix subnet and link, and the driver side in GenTL CTI file added but no error: validate before you enumerate. Once the SDK lists the device, the Wayland fix and the GPU decision above apply word for word.
A compact way to drop USB from the picture on a custom host is a network board camera. MV-CB016-10GM-M-W is a 1.6 MP GigE board-level camera with an M12 mount and a global shutter.
- Sensor format
- 1/2.9"
- Lens mount
- M12
- Interface
- GigE
- Resolution
- Up to 3 MP
Make it repeatable
Five habits prevent the next no-window morning.
- Pin the platform in the launcher. One export line plus a printenv assert means a Wayland session can never flip the demo silently again.
- Keep the 150-frame proof in the repository. Run it after every SDK update. A green frame count turns any later GUI complaint into a display-only problem.
- Watch dmesg at first power-on. Every new camera, cable and hub gets a dmesg -w session. High-speed enumeration and disconnect loops are caught in seconds.
- Budget power explicitly. 4.5 W per USB 3.0 port is the ceiling, hubs divide it, and bus-powered cameras get direct ports or powered hubs.
- Decide the display policy once. Headless automation uses offscreen and frame counts. A watched GUI gets a GPU-backed session or a front-panel client, never a bare virtual desktop on a GPU-less host.
Which fix is yours
Match the console to the table and take the fixes in order. The XDG warning costs one export line. The downlevel panic means offscreen first and a better display second. Silence means enumeration, starting with dmesg and lsusb. A frozen window on a high-speed enumeration means the cable before anything else.
If you are selecting hardware for this kind of host, the camera finder filters USB3 and GigE cameras by resolution and shutter, and the configurator pairs the camera with the rest of the chain. More system-level fixes live on the systems topic page. When the end goal is the image on an HMI at the line rather than a developer GUI, that is a different display path: most HMIs consume RTSP or MJPEG streams, and displaying an IP camera stream in an HMI video player walks it. And if the console still refuses to say which half failed, send the log through the contact page and we will read it with you.
Questions
Why did export QT_QPA_PLATFORM=wayland do nothing?
An export lives only in the shell where you typed it and in processes started from that shell. If the demo launches from another terminal, from a desktop icon or under sudo, the variable never arrives; sudo drops the environment unless you pass sudo -E. Set it and start the demo in the same shell, then confirm with printenv QT_QPA_PLATFORM in that shell before blaming Wayland. For autostart entries and services, set the variable inside the unit or desktop entry itself.
Does the demo need a monitor attached at all?
No. A windowless run proves the camera faster than any GUI: grab a fixed frame count headless and print the result. QT_QPA_PLATFORM=offscreen renders into memory, so a Qt tool can even start without a display, and xvfb-run supplies a virtual X display for programs that insist on one. Use these for automated checks; keep a real or VNC-attached session only when a person needs to watch the image.
What does 'Missing downlevel flags' in the log mean?
It is the WebGPU renderer reporting that the graphics adapter offers fewer features than the application requested. The thread that draws the image dies while capture threads keep logging, so the console looks alive while nothing renders. It shows up on VNC virtual displays, small boards running software rendering and old graphics drivers. The camera is unaffected: prove capture headless, then run the GUI where hardware acceleration exists.
How many frames should a healthy capture test return?
Multiply the advertised frame rate by the seconds you grab. A camera running 30 fps grabbed for 5 s should return about 150 frames; allow a few frames of start-up latency, so 145 or more is healthy. Far fewer frames, or all of them arriving in one burst, point to the link rather than the camera: usually a cable or hub that fell back to USB 2.0 speed.
Do the same fixes apply to GigE Vision cameras?
The window half is identical, because QT_QPA_PLATFORM and the GPU floor belong to the host, not the camera. Enumeration differs: a GigE camera never appears in lsusb. Use the SDK's device enumerator, confirm the camera and network interface share a subnet, and expect an enumeration error long before any GUI code runs. Once the SDK lists the device, every display fix above applies unchanged.



