Linux vision shared library errors: diagnose missing dependencies

A vision application can install successfully yet fail before opening a camera because a native library cannot load. Repeating the Python requirements installer often leaves the underlying problem unchanged. This troubleshooting workflow is for Linux vision hosts, particularly systems where processor capability, operating-system architecture and Python architecture may differ. Start by identifying the failing binary and its dependencies, repair the supported runtime environment, then test camera acquisition without relying on the demonstration interface.

Separate the loader failure from the camera failure

Linux vision shared library errors belong to the software-loading stage. A missing numerical or file-format library does not establish that the camera, cable or acquisition driver is faulty. Conversely, opening an application window does not prove that images are arriving.

Treat the installation as a sequence of independently testable layers:

Resolve the first failing stage before changing later stages. Keep the complete traceback rather than only the final wrapper message. The earliest native-loader error usually gives the most useful dependency name.

If the failure instead involves conflicting library installations inside a larger application stack, use the runtime library mismatch diagnostic workflow. The checks below focus on missing operating-system dependencies and separating import success from stream success.

Record the operating system and process architecture

A processor capable of running a wider instruction set does not prove that the installed user space uses it. Likewise, the kernel architecture alone does not identify the architecture of every Python installation.

Run these read-only checks from the same terminal used to launch the application:

cat /etc/os-release
uname -m
python3 -c 'import sys, struct; print(sys.executable); print(sys.version); print(struct.calcsize("P") * 8)'
python3 -m pip --version

Record the distribution release, kernel architecture, interpreter path, Python version and pointer width. The final command shows which package installer belongs to that interpreter. A bare pip command may refer to a different installation.

A process using 32-bit pointers cannot load a 64-bit native extension directly. Matching pointer width is necessary, but not sufficient: instruction set, calling convention and runtime compatibility must also match.

Inspect the interpreter binary and extension with file when you need stronger evidence than the platform label. Compare the installed package against the software provider's supported operating-system and Python combinations, not just the board's advertised capabilities.

The ARM64 acquisition binary compatibility checks explain the wider architecture decision. For this diagnosis, keep the immediate question narrow: can this interpreter load this extension and every library it requires?

Find the first native dependency that cannot load

Reduce the failing application to the smallest documented import that reproduces the error. Use the provider's minimal import example rather than starting the full demonstration program. A large demo may import optional recording, plotting or numerical modules before attempting camera discovery.

Distinguish three things in the traceback:

• The Python module being imported.
• The native extension that Python tries to load.
• The shared library that the extension, or one of its dependencies, requires.

These are not necessarily the same component. For example, an image-processing extension may depend indirectly on a numerical library. Installing the top-level Python package again may simply reinstall the same binary with the same unmet dependency.

Set the shell variable native_object to the absolute path of the failing extension identified from the traceback or package file listing. Then inspect that file:

file "$native_object"
readelf -h "$native_object"
readelf -d "$native_object"

The ELF header identifies the binary architecture. The dynamic section lists direct dependencies under NEEDED entries and may show library search-path metadata. An indirect dependency requires inspecting the next library in the chain.

For trusted binaries from an approved software source, this command can show resolved dependencies and entries marked as missing:

ldd "$native_object"

Do not run ldd on an untrusted executable or shared object. Use static inspection tools such as readelf when the file's origin is uncertain.

The native library integration guide across toolchains covers cases where a library exists but its binary interface is incompatible. A missing file and an incompatible file need different repairs.

Test likely causes in order

Start with the following order for a fresh installation. Change the priority if the problem began immediately after an operating-system upgrade, environment change or deployment move.

A required runtime package is absent

Test: The loader names a shared library, and dependency inspection reports it as not found. Check the distribution's official package metadata for the package providing that exact library on the installed release and architecture.

Fix: Install the documented runtime dependency through the supported distribution package manager. Do not assume that a development package is required merely because an online example installs one. Development packages often add headers and build metadata that a prebuilt extension does not need.

The binary targets a different operating-system release

Test: The requested library version is unavailable in the official repositories for the installed release, or the software's support matrix excludes that release.

Fix: Use a supported build of the application, a supported operating-system image, or a documented source build against the current environment. Do not add repositories from an unrelated release to satisfy one old dependency.

The library exists outside the loader's search paths

Test: Compare the library's actual location with the extension's search-path metadata and the documented runtime configuration. Where available, inspect the loader cache without modifying it:

ldconfig -p

The cache is not a complete inventory of every library on disk. Libraries loaded through application-specific paths may not appear there.

Fix: Follow the provider's documented environment or loader configuration. Avoid copying libraries into arbitrary system directories. Use temporary search-path changes only as controlled diagnostic tests, not as an unexplained permanent repair.

Architecture or runtime versions do not match

Test: Compare ELF headers and inspect the exact error. A wrong ELF class, a missing symbol version and a missing file indicate different conditions.

Fix: Install matching binaries or rebuild through the documented process. Do not replace the system C runtime manually to satisfy an application extension.

Apply one repair and verify the import again

A useful repair changes one identified cause and produces a repeatable result. Save the original traceback, the package versions involved and the package-manager transaction before continuing.

Use this sequence:

1. Confirm the supported operating-system, interpreter and package combination.
2. Identify the official package or documented installation step that supplies the missing dependency.
3. Apply that single repair and record what changed.
4. Repeat the minimal import using the same interpreter and environment.
5. If another dependency fails, inspect it rather than guessing another package.
6. Retry the full application only after its required imports pass.

Several missing dependencies may appear one after another because the loader stops at the first unresolved requirement. This is not proof that the previous repair failed. It does mean that a successful import is still the acceptance test for the dependency stage.

A virtual environment helps separate Python packages, but it does not automatically supply every system shared library. Containers also retain architecture and host-device integration requirements; they are not a universal repair for unsupported binaries.

For errors caused by a changed development environment rather than absent runtime packages, follow the camera SDK upgrade and build-error checks.

Verify live frames without the demonstration interface

Once imports succeed, switch to the provider's smallest supported acquisition example. Prefer a headless example that reports frame metadata or saves received images without starting a graphical interface.

Configure only what that example requires. Begin with a documented supported pixel format and acquisition mode. If the camera expects a hardware trigger, either supply the documented trigger or select a supported free-running configuration for the test.

Record:

• Whether device discovery succeeds.
• Whether acquisition starts without an error.
• How many completed frames arrive.
• Whether available frame identifiers or timestamps advance.
• Whether dimensions and payload sizes match the selected format.
• Whether image content responds to a moving target or a controlled lighting change.

Use a measured interval to distinguish occasional delivery from sustained acquisition:

For an illustrative test, receiving 240 completed frames over 12 seconds gives:

This measures delivered throughput, not exposure timing or synchronization accuracy. Compare it with the configured test rate and record timeouts or incomplete frames separately. Exclude setup time if the purpose is to measure steady-state delivery.

For the acquisition loop itself, use the continuous image acquisition workflow. If no frames arrive, the USB stream timeout checks help separate transport problems from the earlier dependency failure.

Investigate a frozen or blank display separately

A window may open even when the acquisition worker has stopped. It may also retain its last image while the display event loop is blocked. Neither symptom alone proves a hardware fault.

Compare the headless test with the full demonstration:

A saved image of a stationary scene may look unchanged even when acquisition works. Move a target and compare both content and metadata. Conversely, a changing on-screen counter is weak evidence if it counts display iterations rather than completed camera frames.

Use the blank image window troubleshooting workflow after establishing that acquisition delivers valid buffers. Preserve exceptions from background workers instead of allowing the interface to hide them.

Check compatibility before changing hardware

Replacing the camera does not repair a native dependency in the host environment. Before ordering, confirm the exact acquisition software, processor architecture, operating-system release, transport support and required image formats.

The area scan cameras category and camera finder help narrow hardware interfaces. Catalog interface labels do not establish support for a particular Linux distribution or interpreter.

The LS-CMR-0053 is a GigE area scan camera. Treat it as a candidate only after confirming the required software and host compatibility.

The LS-CMR-0166 is a USB3 area scan camera. Apply the same compatibility check before selecting it for a Linux host.

If you are evaluating vision controllers, request confirmation of the supported operating system and acquisition stack for the specific configuration. A controller category or camera-port description does not establish compatibility with an existing application.

Do not change hardware merely because a full-featured demo imports an optional library unavailable on your host. If the documented acquisition API works independently, a smaller supported application may be the appropriate deployment path.

Preserve a repeatable working baseline

Before handing the station over, complete this short checklist:

• Record the operating-system release and user-space architecture so another host can be matched deliberately.
• Record the interpreter path and package versions so interactive tests and service launches use the same environment.
• Keep the native dependency report with the installation notes so future failures have a baseline.
• Repeat the import and acquisition tests after a reboot to expose temporary environment changes.
• Test under the intended service account because permissions and search paths can differ from an interactive terminal.
• Preserve frame counters, timeouts and worker exceptions in application logs so display faults remain distinguishable from acquisition faults.

If you need compatibility help, send the traceback, architecture details, dependency report and headless acquisition outcome through technical support. For a new station, begin with the camera configuration step after the supported host software requirements are established.