Diagnose ROS OpenCV runtime library mismatch

A successful build does not prove that your ROS node loads the intended OpenCV libraries. The application, image bridge and runtime loader can each select dependencies differently. This troubleshooting sequence helps you identify the libraries inside the running process, align the dependency chain and verify CUDA support without replacing camera hardware or changing unrelated drivers.

Start with the loaded libraries, not the CMake message

A ROS OpenCV runtime library mismatch occurs when the running process uses an incompatible OpenCV installation, despite apparently correct build configuration. Start by recording runtime paths before changing packages or rebuilding software.

There are three separate questions:

1. Which OpenCV headers compiled the application?
2. Which libraries did the linker select for the application and its dependencies?
3. Which shared libraries did the runtime loader actually load?

A CMake discovery message answers only part of the second question. It does not certify the dependency choices made when an existing bridge library was built. It also does not show libraries loaded later by plugins.

The closest background guide, OpenCV version conflicts that crash calibration tools, explains the broader conflict pattern. Here, the diagnostic target is the complete ROS process, including the image bridge and its transitive dependencies.

Rank the likely causes before changing anything

Use the following order as a practical starting point, not a measured probability ranking. Several causes can coexist.

An application feature flag does not add CUDA support to an already compiled OpenCV library. Likewise, discovering a CUDA toolkit during configuration does not prove that the OpenCV binaries selected at runtime contain CUDA functionality.

Change one layer at a time. Otherwise, a successful restart will not tell you which correction mattered.

Capture the executable and launch environment

These examples target a Linux ROS installation using catkin. They assume an example package named inspection, an executable named vision_node and a workspace under your home directory. Substitute your actual package and executable names.

First, inspect the shell from which the node is launched:

printf '%s\n' "$CMAKE_PREFIX_PATH"
printf '%s\n' "$LD_LIBRARY_PATH"
rospack find inspection
rospack find cv_bridge

Package discovery paths help identify active overlays, but they do not prove which shared object enters the process. Record the actual executable path too. A service, launch file or different terminal may use another environment.

Inspect the executable you intend to run:

NODE="$HOME/vision_ws/devel/lib/inspection/vision_node"
readelf -d "$NODE" | grep -E 'NEEDED|RPATH|RUNPATH'
ldd "$NODE" | grep -E 'opencv|cv_bridge'

Use ldd only on trusted binaries you built or obtained through trusted software channels. readelf inspects ELF metadata without running the program.

The NEEDED entries identify requested shared-library names. RPATH and RUNPATH describe embedded search paths, but their loader behavior differs, especially for indirect dependencies. An absolute path chosen during linking also does not necessarily remain an absolute runtime dependency.

A common observation is that CMake selects configuration files under /opt/vision/opencv, while ldd resolves OpenCV libraries under /usr/lib. That discrepancy identifies a search-path problem worth investigating; it does not yet explain every dependency inside the node.

Trace the bridge and the running process

Locate the actual bridge library from the resolved dependencies, then inspect that file with the same tools. Check both its requested OpenCV library names and any embedded search paths.

For a short diagnostic run, the loader can report its search decisions:

LD_DEBUG=libs "$NODE" 2>"$HOME/vision-loader.log"

Run this from the same environment as the failing launch, with any required arguments and ROS services available. The direct command is not equivalent to a launch file that supplies additional environment settings. Apply the diagnostic variable to the affected node when reproducing that arrangement.

Loader output can be large and adds overhead. Use it to find selected files, not to benchmark acquisition timing.

For an already running node, inspect its memory map. With only one diagnostic instance running:

PID=$(pgrep -n -x vision_node)
grep -E 'lib(opencv|cv_bridge)' "/proc/$PID/maps" \
  | awk '{print $6}' | sort -u

If multiple instances exist, identify the correct process explicitly rather than selecting the newest one. Inspect the process after it reaches the failing operation, because plugins may load additional libraries later.

Record the paths for OpenCV core, image processing, required CUDA modules and the bridge itself. Seeing libraries from different installation prefixes is a reason to investigate compatibility. Seeing one prefix alone is not proof that its files came from a consistent build.

Verify headers and runtime build information separately

Add temporary startup logging to the affected node. A standalone test program can be useful, but it may load a different dependency graph and therefore miss the ROS-specific conflict.

#include <iostream>
#include <opencv2/core.hpp>

std::cout << "Header version: " << CV_VERSION << '\n';
std::cout << cv::getBuildInformation() << std::endl;

The header version is compiled into the application. The build-information function reports information supplied by the OpenCV core library executing that call. Compare both with the runtime paths collected earlier.

Look for the CUDA build status and the modules your application actually needs. A CUDA-enabled core configuration does not imply that every optional algorithm module is present.

Treat GPU checks as a second stage:

• Confirm that the intended OpenCV build reports CUDA support.
• Confirm that the necessary CUDA modules are available and loaded consistently.
• Check whether a compatible device is accessible to the process.
• Execute a small representative operation and verify its output.

For example, cv::cuda::getCudaEnabledDeviceCount() can contribute to device diagnosis, but its result alone does not identify a library-path conflict. Missing support, unavailable hardware and driver compatibility require different corrective actions.

For the interface risks behind mixed libraries, use the guide to computer vision library ABI integration across toolchains. Matching a displayed version string is weaker evidence than matching the complete supported binary configuration.

Rebuild a consistent bridge and application chain

Once the evidence identifies a bridge built against another installation, rebuild the relevant dependency chain against one supported OpenCV configuration. Rebuilding only the final executable leaves the bridge's original assumptions unchanged.

1. Choose the supported dependency set. Check the ROS distribution, bridge source release, compiler and OpenCV compatibility requirements. Obtain source and packages from their official upstream channels or authorized distributors.
2. Use a separate diagnostic workspace. Keep the production workspace and distribution packages intact while proving the correction.
3. Include compatible bridge source. Place the appropriate bridge package and your application in that workspace, together with other packages that must share the selected OpenCV interface.
4. Select the intended package configuration. Point OpenCV_DIR at the directory containing the intended OpenCVConfig.cmake, not merely at the installation's top-level directory.
5. Build and inspect the result. Review configuration caches, verbose linker commands and runtime dependencies before testing the complete application.

An example configuration command is:

cd "$HOME/vision_ws"
catkin_make \
  -DOpenCV_DIR=/opt/vision/opencv/lib/cmake/opencv4

The configuration directory varies by installation. This example does not establish that the directory exists on your system. Confirm its contents first.

Use a fresh build configuration when changing dependency installations. Existing package caches can preserve absolute paths even after environment variables change. Do not delete an active workspace as a first diagnostic step.

In application CMake files, use target-specific include paths and linkage. Request the OpenCV components the application actually calls. A minimum version request can accept a newer version; an exact version request narrows selection but still cannot repair an incompatible prebuilt dependency.

After building, start a fresh shell. Source the intended ROS underlay and then the diagnostic workspace overlay, without sourcing unrelated workspaces afterward. Repeat package discovery, dependency inspection and runtime logging.

Prove the correction with a controlled test

Use the same launch method that previously failed. Keep the input image and processing operation fixed while checking the dependency correction.

A useful acceptance sequence is:

1. Confirm that package discovery identifies the intended workspace.
2. Confirm that the running executable is the newly built file.
3. Inspect the loaded bridge and OpenCV paths after processing starts.
4. Compare the header version with runtime build information.
5. Run a representative CUDA operation and check its output.
6. Repeat the test after restarting the node from a fresh shell.

For a practical repeatability check, run 10 starts with 100 test frames per start. That exercises 10 × 100 = 1,000 frames. This is a diagnostic sample, not a reliability guarantee; its purpose is to catch environment-dependent startup differences.

Keep initialization timing separate from steady-state processing. GPU initialization and first-use allocation can make the first operation slower without indicating a library mismatch.

If your application also wraps a camera SDK, inspect whether that layer introduces additional dependencies. The guide to camera SDK build errors after a library upgrade covers the separate rebuild checks that may then be necessary.

Know when rebuilding the bridge is the wrong fix

Do not rebuild the bridge merely because an exception mentions CUDA. First establish that the bridge contributes the conflicting dependency.

If all relevant libraries come from the intended compatible build, investigate the actual exception. Possible next branches include unavailable GPU hardware, unsupported operations, invalid image types or application-level memory errors. Each needs evidence beyond the configuration transcript.

Sometimes the ROS distribution's supported bridge cannot safely share the required custom OpenCV build. A separate processing process can provide a cleaner boundary than forcing incompatible libraries into one address space. Exchange images through an explicit interface, then measure serialization cost, memory use and latency.

A container can make deployment more reproducible, but it does not automatically resolve conflicting libraries inside the container. GPU access and compatible dependencies still require configuration.

Nor does changing the camera fix software dependency selection. If the actual symptom is dark USB acquisition rather than a CUDA exception, follow USB3 camera image troubleshooting in ROS tools instead.

Keep acquisition hardware separate from software acceptance

Use a recorded image first when possible. Once the dependency chain passes, restore live acquisition and verify timestamps, image encoding and frame delivery independently.

For a separate live-input bench, the LS-CMR-0053 provides a GigE acquisition option. Its interface does not determine which OpenCV libraries the node loads.

The LS-CMR-0166 provides a USB3 acquisition option. Select the camera around the inspection requirement, not as a remedy for this software error.

Use the area scan cameras category and camera finder when acquisition requirements are established. If deployment needs dedicated camera connections and processing hardware, review vision controllers separately from OpenCV compatibility.

Before accepting the correction, check:

• Dependency evidence: save the executable, bridge and OpenCV runtime paths.
• Build evidence: record configuration locations, compiler settings and required modules.
• Launch evidence: reproduce startup from the intended service or launch environment.
• Functional evidence: verify processing output, not just successful initialization.
• Acquisition evidence: restore live images only after the fixed-input test passes.

If you are planning a new acquisition system, start with the camera configurator. For component-selection help, send the inspection requirements and dependency findings through technical support.