Headless camera sensors need a valid graphics device id

create_camera_sensor returns -1 in your headless run, and the next line dies with could not find camera with handle -1 in environment 0. The cause sits one call earlier and one idea deeper: headless turns off the on-screen window, not the need for a graphics device. Camera sensors render their images on a GPU, so a sim created with graphics_device_id=-1 cannot create sensors at all. This page is for anyone running a rendering or simulation perception stack on a rack-mounted vision controller or a GPU server. You will leave with both failure signatures decoded, a two-GPU pinning example with the arithmetic shown, the fix in order, and the decision rule for enable_tensors.

What the error is telling you

The log line reads [Error] [carb.gym.plugin] SetCameraLocation: Error: could not find camera with handle -1 in environment 0. The message names set_camera_location, but the blame sits one call earlier. create_camera_sensor returns an integer handle; -1 is its no-sensor value. The placement call then searches environment 0 for a camera with handle -1, finds nothing and raises the error. Debug the creation, not the placement: the camera never existed.

Two failure signatures show up in practice, and they need different first moves:

Both signatures share one root: the process tried to run a rendering workload without a usable graphics device, or with one it cannot address cleanly. The three causes below cover the ways that happens.

Cause 1: graphics_device_id=-1 removes rendering, not just the window

Passing -1 asks for compute without graphics. Physics, state reads and your own CPU code paths keep working, which is why the sim looks healthy right up to the sensor call. A camera sensor is different: it is a rendered view, produced by the graphics backend on a real device. With no graphics context the creation fails and hands back -1 quietly; the error only surfaces when you next touch the handle.

The fix on a single-GPU machine is one character: create the sim with graphics_device_id=0. Keep --headless if you want no window, because the two settings are independent. Headless decides what is displayed; the device id decides whether sensors can render at all.

Cause 2: two or more GPUs, and nobody pinned one

On a machine with two or more GPU cards, each subsystem picks its own device: the sim's graphics context lands on one card, the CUDA runtime that wraps your tensors lands on another, and create_sim segfaults at the join. The signature is hard to miss: the identical script runs on a single-GPU laptop and crashes on a dual-GPU workstation.

Pin the process to one card before it launches:

export CUDA_VISIBLE_DEVICES=0

The process now sees exactly one device, so graphics and tensors share the same silicon, and 0 becomes the only valid device id for create_sim.

Containers follow the same rule: pass the GPU through and make it visible first, as in the depth camera GPU visibility fix in Docker. Training jobs that segfault on multi-GPU servers hit the same join from the training side; the YOLO segmentation fault fixes start one step earlier in that stack.

Cause 3: enable_tensors=False hides the crash, not the cause

Setting enable_tensors=False in the camera properties makes the segfault disappear, because the sensor then skips the GPU-tensor interop path that has no graphics context to live on. Treat that as a diagnosis, not a fix: the run still has no working rendering device, and code that calls get_camera_image_gpu_tensor and wraps it with gymtorch.wrap_tensor now has nothing to wrap.

Take the tensors-off road only when you also give up GPU tensors and read images back over the CPU. If your model consumes the tensor on the GPU, fix the device and leave tensors on, keeping the pipeline on-card the way the GPU tensor input pattern expects. The same interop layer serves on-screen display when you do want a window; the CUDA OpenGL interop guide for 3D camera display covers that side.

Worked example: pinning one GPU on a two-GPU vision server

The inputs, with their sources:

• 2 GPU cards installed — the dual-GPU workstation case.
• Device ids start at 0, so the cards answer to 0 and 1 — standard CUDA numbering.
• Pin: CUDA_VISIBLE_DEVICES=0 — exactly one card left visible.
• Sim argument: graphics_device_id, the value handed to create_sim.

The rule in words: a process can only create a sim on a device id between 0 and the number of visible GPUs minus 1, and a camera handle is usable only when it is 0 or higher.

The arithmetic: unpinned, the process sees both cards, so valid ids run 0 to 2 - 1 = 1. Pinned to card 0, the process sees 2 - 1 = 1 GPU, so the only valid id is 0. Passing graphics_device_id=1 after the pin addresses a card the process can no longer see — a guaranteed failure.

The result: create_sim on device 0 succeeds, and create_camera_sensor returns 0 — a real handle, at the bottom of the usable range. set_camera_location then places that sensor with its eye at (1.2, 0, 2.5) looking at (0, 0, 1.2). The placement distance checks out as d = √[(1.2 - 0)² + (0 - 0)² + (2.5 - 1.2)²] = √(1.44 + 0 + 1.69) = √3.13 ≈ 1.77 units — meters in the default sim set-up — from its target.

The decision: proceed when the handle is 0 or higher; stop and fix the device when it is -1. Keep exactly one visible GPU per process. The moment a second card is visible, the process is back in the split-device zone where create_sim crashes.

The fix, in order

1. Smoke-test the machine before your code: run the interop example headless with python interop_torch.py --headless. If the example fails, the device set-up is the problem, not your script.
2. Pin one GPU in the shell or service file: export CUDA_VISIBLE_DEVICES=0. Do it before launch, never inside the running process.
3. Create the sim on a real graphics device — 0 under the pin. Never pass -1 to a run that creates camera sensors.
4. Log the handle from create_camera_sensor immediately and refuse to continue on a negative value.
5. Only then place the camera with set_camera_location, giving both the eye and the target as real coordinates.
6. Check the tensor device before inference or training: the wrapped tensor must report the same GPU the sim renders on. Multi-view stacks slice per camera from one buffer, as in the per-view GPU tensor slicing guide.
7. Re-run step 1 after every driver or SDK update; alignment between the two is its own failure mode, as the SDK and firmware version alignment guide shows.

Where this bites on real deployments

Rack controllers and remote servers run headless all day, so a perception stack that renders sensors or feeds GPU tensors needs a graphics device the process can see, sized like any other resource. Three shapes cover most deployments: a CPU vision controller with PCIe expansion takes a rendering card, an AI inference terminal carries its cards on board, and a multi-GPU training server makes per-process pinning mandatory.

The MV-VC5525-256G70-NN pairs an Intel Core i5 with 32 GB of memory and PCIe expansion, so a rendering card fits beside the capture ports. The MV-VAC5724-256G02 carries two AI inference cards on board, with PoE camera ports and 8 built-in light channels. The MV-TS1004-256GR-960G16TR10 is a quad-GPU training server, exactly the box where the per-process pin from the worked example is mandatory; give each job its own card.

When the trained stack moves onto real hardware, the discipline follows it: depth and stereo 3D sensors build their own GPU buffers on the same box, and the unsupported compute device fixes apply when an SDK refuses a device the OS can see.

Prevent it on the next build

Four habits keep this failure class out of your logs:

• Create every sim on a real graphics device id, even in headless runs; reserve -1 for pure compute jobs that create no sensors.
• Pin the GPU in the launcher or service definition, so every process starts with exactly one visible device.
• Log every handle at creation and stop the run on a negative value.
• Keep the graphics stack, the CUDA runtime and the SDK build aligned, and re-run the interop example after each update.

Assemble the rest of the rig — capture ports, light channels, trigger wiring — in the build-a-system configurator, and send unusual deployments through the contact page.