IMD SolutionComputing LibraryShop main store

Troubleshooting

Fixing a Docker shared library error on an edge PC

Edge computing and IIoT Published 8 min read

Short answer

A container on an edge PC that exits with an error while loading shared libraries was built for a different controller firmware generation than the one installed. Pull the image revision rebuilt for your firmware, recreate the container, and verify with ldd, the linker cache and a restart-count check. Never symlink across major library versions: on a machine driving physical outputs, a mismatched library produces wrong I/O data instead of a clean error.

On this page
  1. Why does my container exit with an error while loading shared libraries?
  2. Why does the same image run on FW18 but fail on FW19 and FW21 SP2?
  3. How do I confirm which library mechanism is failing before changing anything?
  4. What is the fix for the liboms.so.0 failure on a 750-8217?
  5. Can I just symlink liboms.so.0 to the library the firmware provides?
  6. How do I verify the container is really serving I/O again?
  7. Questions asked

On an edge PC or a machine controller, a container that exits at start with an error while loading shared libraries was almost never built for the firmware now installed on the box. The binary asks the dynamic linker for a firmware-supplied object by soname; on a mismatched generation the linker cannot resolve it, and the process dies before its first instruction runs. The fix that holds is to pull the image revision rebuilt for your firmware, delete the stale container and its cached layers, recreate with the documented run arguments, and prove the result with ldd, the linker cache and a restart-count check. Never bridge the gap with a symlink across major library versions: on a machine driving physical outputs, a mismatched library produces wrong I/O data instead of a clean error.

Why does my container exit with an error while loading shared libraries? #

The dynamic linker could not resolve a shared object that the binary requests by name before its first instruction runs, so the process exits at start: the object is absent, invisible to the container, or built for a different firmware generation than the one on your machine.

The reported case is a PFC200 750-8217 running pfc-modbus-server, the container that exposes the controller's local KBUS I/O as Modbus TCP, acting toward the network like a 750-352 Modbus coupler. It exits immediately with this linker message:

kbusmodbusslave: error while loading shared libraries: liboms.so.0:
cannot open shared object file: No such file or directory

A direct install of the same application failed the same way, which rules out container packaging as the culprit: the object is supplied by the controller firmware, and the application resolves it by soname at start. Three mechanisms print this exact message:

  • Namespace isolation — the file exists on the host, but the container's mount namespace never sees it. A container only resolves libraries carried in its image or bind-mounted in, so the file's presence on the host proves nothing about the container's view.
  • Soname drift — the image links a specific ABI revision of the firmware-supplied library set. Move the firmware a generation, and the object's soname suffix, path or dependency chain moves with it.
  • Broken transitive dependency — the named object is present, but one of its own dependencies is missing, and the linker reports the top-level name, sending the search down the wrong path.

Why does the same image run on FW18 but fail on FW19 and FW21 SP2? #

Because the image links against the firmware-supplied library set of the generation it was built on: field reports show it running on FW18 and failing on FW19 and FW21 SP2, and the published revision rebuilt on FW21 corrects the failure — the matched build is the answer.

liboms.so.0 is not carried inside the image; the binary asks the controller firmware for it by soname at start. The FW18-era build resolves only on the generation it was linked against; the newer firmware provides a changed library set, and a native install failed identically on it for the same reason: package and container link the same firmware-supplied objects.

Your decision rule is one line: the image generation must equal the firmware generation, and when they differ, nothing you shuffle inside the container filesystem is the fix.

How do I confirm which library mechanism is failing before changing anything? #

Run three commands inside the container, read them against the table below, and you can separate namespace isolation from soname drift from a broken transitive dependency in about two minutes, before you touch the image or the firmware.

The process dies at start, so catch the container during an up-window of its restart loop, or start a throwaway shell from the image with sh as the command. The examples use kbus-modbus as the container name and wago/pfc-modbus-server as the published image name; substitute yours.

docker exec -it kbus-modbus sh
ldd $(command -v kbusmodbusslave) 2>&1 | grep 'not found'
find / -name 'liboms.so*' -type f 2>/dev/null
ldconfig -p | grep oms

Here ldd prints every soname the binary cannot resolve, find shows what the container filesystem actually holds, and ldconfig -p prints the linker cache — what the loader will accept by name.

What you see Mechanism at work What to do
ldd prints liboms.so.0 => not found and find returns nothing Namespace isolation Use the image built for your firmware, or bind-mount the host library directory read-only, matching soname only
The file is present as liboms.so.1, not .so.0 Soname drift Move to the image revision built for your firmware generation; never bridge the suffix with a symlink
liboms.so.0 resolves, but ldd on the object itself lists another missing file Transitive dependency Chase that dependency; in practice it is the same firmware mismatch one layer down

Read the suffix as the number it is: a binary requesting soname liboms.so.0 against a cache that offers liboms.so.1 is a gap of one major ABI generation (1 - 0 = 1), and the dynamic linker does not bridge a major-version gap on its own — which is why no command inside the container can make the old build run. Once the library question is settled, most remaining container faults on this hardware, from networking to management-UI quirks, follow the same diagnose-first path laid out in resolving Docker and Portainer container issues on PFC-series controllers.

What is the fix for the liboms.so.0 failure on a 750-8217? #

Pull the current image revision rebuilt for your firmware generation, delete the stale container and its cached image, recreate the container with the run arguments the image documents, and prove a clean start in the foreground before you hand it a restart policy.

  1. Read the firmware generation off the controller first; it selects the image revision, never the other way around.
  2. Delete the stale container and its cached layers so the old build cannot come back: docker ps -a, then docker rm -f kbus-modbus, then docker images, then docker rmi with the id of the old revision.
  3. Pull the current revision: docker pull wago/pfc-modbus-server. If you pin tags, take the tag the image documentation lists for your firmware generation.
  4. Recreate with the run arguments the image documents for your controller — access to the KBUS device, plus host networking or an explicit publish of the Modbus TCP port — and start in the foreground first: docker run --rm -it wago/pfc-modbus-server. A linker error here is visible immediately; a clean start proves resolution. The create-and-test sequence is the same one a guide to configuring a C# .NET 6 container on a PFC200 walks through, whatever the image inside.
  5. Once the foreground start is clean, rerun the same command with --rm -it replaced by -d --restart unless-stopped for production.
  6. Give the KBUS one owner. The local I/O bus serves a single owner at a time — the CODESYS runtime, this Modbus server container, or an MQTT KBUS service. Check the firmware documentation for which services claim it, and stop the CODESYS runtime if the container is meant to own the bus. If your control logic runs in Node-RED, the project documentation recommends its MQTT-based KBUS API over polling the register image; the one-owner rule holds either way.

Keep the deployment deliberate afterwards: pin an explicit revision instead of floating tags, one function per container — the same discipline that keeps a data-store container healthy when you are deploying an edge data store in Docker on a controller PC. If no rebuilt revision exists for your generation, the fallback is the older generation the existing image was built against; treat a firmware downgrade as the fallback, never the plan, and back the controller up before it.

Never across major versions: a symlink from liboms.so.1 to liboms.so.0 can let the process start and then fail unpredictably at KBUS access time, so the decision is zero cross-version links, and a bind mount earns its place only when the soname matches.

A library that answers the wrong soname was never built to that ABI. If the process loads anyway, it fails later, at bus access time, and the visible symptom is wrong I/O data: outputs driven from a register image assembled by code that never promised to match. On a machine driving physical outputs, a wrong register state is a safety event, not a log entry, so treat any container that starts only after a manual library link as unverified until the readback check below passes against live signals.

The read-only bind mount of a host library directory is the legitimate use of the shared-library volume pattern: it fixes namespace isolation when the soname already matches and you want to update library files without rebuilding the image. It fixes visibility, never ABI drift — mounting the newer firmware's library into an older image recreates the same crash one directory deeper.

How do I verify the container is really serving I/O again? #

Four checks decide it: the container stays Up with a restart count of 0 across a 5-minute window, TCP 502 is listening, the module tree enumerates correctly, and a live input toggles a register you read back — pass all four, not just a running process.

Worked example, illustrative timeline: you recreate the container at 14:05 with the restart policy active. At 14:06, docker ps shows STATUS Up 58 seconds and RESTARTS 0 — 58 s of continuous up time with 0 recorded exits means the linker resolved. At 14:10 the same line reads Up 5 minutes (300 s), still RESTARTS 0. Before the fix, that line at 14:06 read RESTARTS 4: four failed starts inside 60 s. The decision: 0 restarts across a full 300 s window after a clean foreground start means fixed; a climbing count means the process still dies at start, so return to the table above.

Then check the listener: Modbus TCP is served on TCP port 502, the port assigned to the protocol, so ss -ltn on the controller, or a port check from the engineering PC, must show the Modbus port in the listen state.

Connect WAGO-IO-Check to the controller's IP address. The image documents the container as IO-Check's counterpart, so a correct deployment enumerates the physical module tree; a module count or ordering that does not match the DIN rail points to a KBUS ownership conflict, not a library problem.

Last, read a discrete input mapped to a module you can reach, toggle the field signal, and watch the register follow the wire. A register that tracks the contact proves the data path end to end and clears the container for production.

Questions asked

The error names kbusmodbusslave but the application is called kbusmodbusserver — which one is failing?

They are the same component across image revisions: published material names it kbusmodbusserver, while the runtime error prints kbusmodbusslave as the executable name. Before scripting any start or stop wrapper, list what the image actually ships, for example with docker exec followed by the container id, ls -l and /usr/bin, and use the name you find there.

Other containers fail with a missing libgcc_s.so.1 — is that the same problem?

It is the same class of failure: a binary asks the dynamic linker for an object by soname and the object is not resolvable in that container at start time. The diagnosis is identical — run ldd on the failing binary inside the container, compare what it requests with what the image and firmware provide, then fix the mismatch with a matching build rather than a hand-made link.

Where should the corrected image revision come from?

From the official repository that publishes the image for your controller, or the vendor channel your plant already uses for controller software. Check the revision notes for the firmware generation each tag targets, pull that tag explicitly, and never substitute an unofficial mirror of a controller-specific image: you cannot verify what a mirrored layer carries, and the library set inside it is exactly what failed.

What does a firmware downgrade to FW18 cost me?

More than the library fix is worth in most plants. Dropping back a firmware generation resets or migrates the controller's application, its network configuration and its certificates, so a full backup of settings and application comes first. Treat FW18 as the fallback when no rebuilt image revision exists for your generation, not as the routine way to make an old image run.

Keep reading

  • How-to

    Run Python and Node-RED beside PLC code on an edge PC

    Keep the IEC 61131-3 program in the controller runtime and run Python and Node-RED as separate Docker containers on the same edge PC. Exchange data over one MQTT interface with a fixed publish period, and declare data stale after three missed periods. One container per workload, and nothing from Python or Node-RED inside the control project.

    Edge computing and IIoT

  • How-to

    Deploying Edge Data Store in Docker on a controller PC

    Run Edge Data Store as a Docker container on the controller-class edge PC and let its OPC UA adapter ingest the local server over localhost. Define egress targets, buffering and forwarding schedules in the JSON configuration, size the buffer from tag count, scan rate and outage target—50 tags at 1 event/s across an 8-hour outage is about 288 MB—and sign off only after a live pulled-cable test.

    Edge computing and IIoT

  • How-to

    Install licensed software on an industrial edge PC

    Install vendor-licensed container software on an industrial edge PC by passing four gates in order: a purchased license with the installer obtained only from the vendor, a verified Docker engine, an installer build that matches the CPU, and a proven open-internet path before the pull. Vendor guidance budgets the install command at 30 minutes to 1 hour; at a 5 Mbit/s link a 2 GB payload alone needs about 53 of them.

    Edge computing and IIoT