> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.stereolabs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.stereolabs.com/_mcp/server. # MIPI Troubleshooting This guide addresses the **most common issues** you may face while setting up a **[ZED X One Core](/docs/products/cameras/zedxone-core/)** camera with a [ZED Link MIPI](/docs/products/embedded/zed-link-capture-card/mipi) capture card on NVIDIA® Jetson™ devices. Follow the steps below to troubleshoot and resolve these issues effectively. > **Note** > > This page covers the **MIPI CSI-2** capture cards only. If you are using a ZED Link Mono, Duo, or Quad card with a ZED X, ZED X Mini, ZED X Nano, or ZED X One (GS, S, 4K) camera, refer to the [GMSL2 Troubleshooting](/docs/products/embedded/zed-link-capture-card/gmsl2/troubleshooting) page instead. The ZED Link MIPI Quad is used in two host configurations, and they fail in different ways. The page is organized accordingly: * [Common checks and commands](#common-checks-and-commands), which apply to both configurations. * [Jetson AGX Orin Developer Kit](#jetson-agx-orin-developer-kit), where the capture card is plugged directly into the carrier board. * [Holoscan Sensor Bridge on Jetson AGX Thor](#holoscan-sensor-bridge-on-jetson-agx-thor), where the camera data travels over Ethernet. Start with the common checks, then continue in the section matching your host. --- ## Common checks and commands > **Warning** > > The ZED X One Core does **not** support hot-plugging. Cameras must be connected and disconnected **only when the host is powered off**, and any change to the hardware configuration requires a **full reboot** of the host to take effect. ### List the cameras seen by the ZED SDK This is the first command to run on any host, and the one that tells you whether the problem is above or below the ZED SDK: ```bash ZED_Explorer --all ZED_Studio --list ``` If no ZED X One Core is listed, check the following points in order: 1. **The cameras were connected before boot.** The MIPI capture pipeline is configured at startup, so a camera connected on a running system is never enumerated. Power the host off, connect the cameras, then power it back on. There is no daemon restart or rescan that avoids the reboot. 2. **The camera is a ZED X One Core.** A [GMSL2](/docs/products/embedded/zed-link-capture-card/gmsl2#what-is-gmsl2) camera (ZED X, ZED X Mini, ZED X Nano, ZED X One GS, ZED X One S, ZED X One 4K) cannot be connected to a ZED Link MIPI card. The interfaces are electrically and mechanically different. 3. **The driver matching your host is installed.** The driver differs between the two configurations: see [The wrong driver is installed](#the-wrong-driver-is-installed) for the AGX Orin Developer Kit, and [No camera is detected](#no-camera-is-detected) for the Holoscan Sensor Bridge. Then continue with the section matching your host. ### Inspect the capture pipeline Kernel messages related to the capture pipeline: ```bash sudo dmesg | grep -i -E "zed|imx|csi|vi-output" ``` The ZED Diagnostic tool `dmesg` option gives a quick overview. Attach its report to any support request: ```bash sudo /usr/local/zed/tools/ZED_Diagnostic --dmesg ``` ### The frames of the cameras do not look synchronized The ZED Link MIPI Quad synchronizes its channels in hardware through an onboard FPGA, with a precision of **15 µs**. No jumper or external wiring is required. Software timestamps, however, are assigned when the driver receives each frame and may show millisecond-level jitter. Frames are considered synchronized when the difference between their timestamps is **less than one frame period** (`1000/FPS` ms). A jitter within that window is expected behavior and does not indicate a synchronization fault. --- ## Jetson AGX Orin Developer Kit The checks in this section assume a **NVIDIA® Jetson AGX Orin™ Developer Kit**, where the capture card is plugged directly into the `CAMERA` connector (`J12`) of the carrier board. The assembly procedure is described in the [ZED Link MIPI Quad on AGX Orin](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-orin-agx-devkit-setup) setup guide. ### The capture card is not fully seated On the AGX Orin Developer Kit, the card is powered through the 120-pin `J10` Samtec connector. If the board-to-board connection is not fully mated, the card receives no power and no camera is detected. Power the devkit off, press the card down firmly until the two connectors are fully mated, and tighten the three screws. > **Note** > > The `J12` 5 V input of the capture card is **not** required for normal operation on the AGX Orin Developer Kit. It is only needed to power the card when programming the FPGA through `J16`. A missing `J12` supply is not the cause of a detection failure. ### Only some of the cameras are detected When part of the cameras enumerate correctly and others do not, the problem is almost always on the affected channel rather than on the card or the driver. **Power the Developer Kit off before each of the following steps**, and boot it again to check the result. Every one of them changes the hardware configuration. * **Reseat the I-PEX cable** at both ends, on the capture card (`J1` to `J4`) and on the [back of the camera](/docs/products/cameras/zedxone-core/interfaces). The plug must go in straight and be pressed down until fully seated. * **Swap the cable** with one from a channel that works. If the fault follows the cable, the cable is damaged. * **Swap the channel.** Move a working camera to the suspect channel. If the working camera also fails there, the channel or its connector is at fault; contact support. * **Check the cable length.** The ZED Link MIPI Quad supports cables up to **50 cm**. Longer or lower-quality cables degrade signal integrity and can make a channel unreliable or intermittent. > **Warning** > > Micro I-PEX connectors are **fragile**. Never force the plug, never insert it at an angle, and never pull on the wires to disconnect it: always handle the plug body. Damaged connectors are not covered by the warranty. ### The wrong driver is installed The ZED Link MIPI Quad and the [GMSL2](/docs/products/embedded/zed-link-capture-card/gmsl2#what-is-gmsl2) ZED Link cards use **different driver packages**. Installing the GMSL2 ZED Link driver on a system equipped with a MIPI capture card, or the reverse, leaves the capture pipeline unconfigured and no camera is detected. List the StereoLabs packages currently installed: ```bash sudo dpkg -l | grep stereolabs- ``` If the installed package does not match your capture card, remove it before installing the correct one: ```bash sudo dpkg -r stereolabs- ``` Then download the package matching your capture card and your Jetson™ Linux (L4T) version from the [ZED X Camera Drivers](https://www.stereolabs.com/developers/drivers) page, install it, and **reboot**. > **Note** > > If the ZED Link MIPI package is not yet listed on the drivers page for your L4T version, please contact [support@stereolabs.com](mailto:support@stereolabs.com). ### Upgrading the ZED Link MIPI driver To upgrade the driver, the previously installed version must be uninstalled first: ```bash sudo dpkg -l | grep stereolabs- sudo dpkg -r stereolabs- ``` Install the new package, then **reboot** the Jetson™ device. --- ## Holoscan Sensor Bridge on Jetson AGX Thor The checks in this section assume a ZED Link MIPI Quad mounted on an **NVIDIA® Holoscan Sensor Bridge**, connected to a Jetson AGX Thor™ Developer Kit over Ethernet. The assembly and installation procedure is described in the [ZED Link MIPI Quad on AGX Thor with Holoscan Sensor Bridge](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-agx-thor-devkit-setup) setup guide, referred to below as *the setup guide*. Because the camera data travels over Ethernet, the two things to check first are the **network link to the bridge board** and the **FPGA firmware** it runs. ### No camera is detected | Symptom | Likely cause and fix | | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ZED_Studio --list` shows **no device** | The network link is down: check `ping 192.168.0.2` and redo [Configure the host network](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-agx-thor-devkit-setup#step-2-configure-the-host-network). Or the driver is not installed: check that `/usr/lib/nvsipl_drv/libar0234_library.so` exists, and redo [Install the ZED Link MIPI driver](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-agx-thor-devkit-setup#step-4-install-the-zed-link-mipi-driver). | | Only one of the two cameras is detected | Check that the cameras are connected to `J1` and `J2`. A camera plugged into `J3` or `J4` is never detected with the Holoscan Sensor Bridge. Then reseat the I-PEX cable at both ends and reboot. | | `UnsupportedVersion: hsb_ip_version=0x...`, or the board enumerates but never streams | The FPGA firmware is too old. Run `hololink-enumerate` and check `hsb_ip_version`: it must be `0x2510` or newer. Upgrade it with `hsb_flasher`, see [Check the FPGA firmware version](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-agx-thor-devkit-setup#step-3-check-the-fpga-firmware-version). | | The camera is detected but **fails to open**, with an `NV_PLUGIN` or `RegisterAutoControlPlugin` status error | The auto-control plugin could not validate the ISP tuning file. Check that the `.nito` file is deployed and that `nova0_camera.json` refers to the correct `platformConfig`, see [Install the ZED Link MIPI driver](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-agx-thor-devkit-setup#step-4-install-the-zed-link-mipi-driver). | | The live view is **black**, or no frame arrives | Check that the cameras are powered and that the link is up, and confirm that the requested resolution and framerate are supported, see [Verify the installation](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-agx-thor-devkit-setup#step-6-verify-the-installation). | | `/var/log/syslog` grows by several GB and fills the disk | NVIDIA® SIPL debug output, see [Clean up the SIPL log output](#clean-up-the-sipl-log-output) below. | > **Note** > > The driver used in this configuration is delivered by StereoLabs on request and is **not** the package published on the drivers page. Its installation and removal are described in the [setup guide](/docs/products/embedded/zed-link-capture-card/mipi/zed-link-mipi-quad/jetson-agx-thor-devkit-setup#step-4-install-the-zed-link-mipi-driver). ### Recover the Ethernet connection If the bridge board was reachable before and `ping 192.168.0.2` suddenly fails, for example after a reboot of the board or because of a stale ARP entry, flush the neighbor cache and bounce the interface: ```bash sudo ip neigh flush dev mgbe0_0 sudo ip link set mgbe0_0 down sleep 2 sudo ip link set mgbe0_0 up sleep 3 ping -c 3 -W 2 192.168.0.2 ``` If `ping` succeeds afterwards, run `ZED_Studio --list` again. ### Clean up the SIPL log output While streaming, the NVIDIA® SIPL pipeline writes a large amount of debug output to syslog, which can fill the disk in a few minutes: ```bash ls -lh /var/log/syslog # check the size sudo truncate -s 0 /var/log/syslog # empty the file, do not delete it: rsyslog keeps it open sudo journalctl --vacuum-size=200M ``` > **Note** > > If the messages are `Capture block get output buffer timed out` or `Queue is empty`, the pipeline is receiving no frame at all. Fix the root cause, see the **black live view** entry of the table above, instead of only clearing the log. --- ## Contact Support If you are unable to resolve your issue, please reach out to us [for further assistance](https://community.stereolabs.com/).