Running 3D camera control software in Docker: fix startup failures

You built a container for your 3D scanner's control software, the install went cleanly, and the application crashes on startup: a missing resource folder, an assertion in the discovery library, or a silent abort before any log output. These symptoms often point to an environment problem, but they do not establish whether the scanner or SDK is defective. Work through the failure layers separately—working directory, display dependencies and multicast discovery—with a test for each before changing scanner settings.

If your problem is discovery on a plain Linux host rather than in a container, start with the Linux GigE Vision camera discovery troubleshooting guide instead; the container-specific network parts below assume you have already ruled out host-side issues.

Symptom: runtime error about a missing folder in the working directory

One startup failure looks like this: the control binary starts, prints its version banner, then terminates with a standard library exception saying a theme or resource folder is missing in your working directory.

A likely cause is resource-path resolution. The application may resolve its UI resources relative to the directory it was launched from, or from a path variable that the package normally sets in a login shell. Inside a container, your entry point may run from another directory, and there may be no login shell to source the profile. Also check that a bind mount has not hidden the installed resources.

Three fixes, depending on the application's documented layout:

1. Launch the application with its resource directory as the working directory: set working_dir in your container configuration or WORKDIR in the Dockerfile.
2. Set the vendor's documented path environment variable, if available, to the absolute location of the resource folder in your image.
3. If the package permits resource relocation, copy the complete resource folder to the documented lookup location while preserving permissions and directory structure.

Symptom: assertion failure in the mDNS discovery library

Fix the folder error and you may encounter a second crash: an assertion like avahi_service_browser_new: Assertion 'client' failed, followed by a core dump.

This points to discovery-client initialization, not necessarily to missing multicast packets. The application may have failed to create its Avahi client because the daemon or its D-Bus connection was unavailable. Check the messages immediately before the assertion and inspect the relevant service logs.

Test browsing on the host, then inside the container where the application runs:

avahi-browse -art

Compare the results with the service type documented for your scanner. A daemon connection error requires an IPC or service fix first. If browsing runs successfully but the expected service is absent, investigate announcements, interfaces, firewall rules and network boundaries.

Choose a supported arrangement:

1. On a supported Linux deployment, test --network host to remove the default bridge boundary. This shares the host's network namespace, but it does not automatically give the container access to the host's Avahi daemon or D-Bus socket. The application still needs a documented, working daemon connection.
2. If you must keep bridge networking, provide the required Avahi and D-Bus services through a supported configuration. Crossing between the physical camera network and the container bridge may also require an explicitly configured mDNS reflector on a component connected to both networks. Installing a daemon inside the container alone does not provide that path.
3. Skip discovery if the SDK documents direct connection by IP address. A reachable, stable address can remove discovery from the production startup path, although acquisition traffic still needs correct routing and firewall rules.

The GenTL camera discovery in containers article provides related network checks. Confirm the actual discovery protocol, however: GigE Vision discovery is not the same protocol as mDNS, and a 3D scanner may use either a standard or a device-specific mechanism.

Symptom: the GUI application will not start on a headless image

Some control applications use Qt or another GUI framework. Depending on the build, they may need display client libraries, font packages or other runtime dependencies even when you do not intend to interact with a window. A slim base image can therefore produce loader errors or a display-platform initialization failure.

Your options:

• Install the runtime packages the vendor lists for the application. For an X-based commissioning session, configure DISPLAY, the required display socket and narrowly scoped authentication. Avoid blanket xhost access allowances.
• Use xvfb to provide a virtual X display when the application supports that arrangement. This can support automated starts without a physical display, but it does not replace missing libraries or guarantee rendering compatibility.
• Prefer the SDK's documented headless API for production when available. It can remove the GUI process from the acquisition path, but verify its own runtime dependencies rather than assuming it needs no display-related packages.

The host matters less than the network design

The container packages user-space software, but the host still supplies the kernel, device drivers and hardware resources. Check the SDK's supported host requirements, especially for USB access, GPU processing or other hardware acceleration. Keep the scanner on its own subnet where practical: this keeps large depth frames off the plant LAN and follows the advice in vision cell network isolation from a busy plant LAN.

A vision controller can provide a multi-port host for this arrangement. For example, the MV-VC3301H-128G66 provides 5+ LAN ports, an Intel Core i3 processor and 8 GB of memory. The MV-VC5525-256G70-NN provides an Intel Core i5 processor, 32 GB of memory and PoE camera ports. These specifications identify candidates, not guaranteed scanner capacity: benchmark the intended processing workload and verify operating-system compatibility. Check each device's power requirements before planning to use PoE.

For DNS inside containers—a different failure, but one that appears in the same projects—there is a useful knowledgebase article on Docker Debian DNS SERVFAIL resolution failures if your container cannot resolve names at all.

Worked example: a minimal startup checklist

Here is a sequence for testing a fresh scanner control container, with the reasoning at each step:

1. Base image: choose a maintained Linux release explicitly supported by the SDK. An older release is not automatically safer, and an unsupported newer release can also introduce compatibility problems.
2. Install the SDK package and its documented runtime dependencies. Include GUI dependencies only when the selected application or API requires them.
3. Set the working directory to the documented resource location, or set the vendor's documented path variable, so the resource folder resolves.
4. Test discovery on the host and inside the container. For an mDNS-based scanner, verify the Avahi client connection separately from network visibility. Test host networking only within the deployment's security requirements.
5. If supported, connect by fixed IP in your application code so startup does not depend on discovery. Verify acquisition as well as connection.

Also estimate the stream payload before choosing a host or network layout. Consider an illustrative depth image with a resolution of 640 × 480 pixels, using 2 bytes per pixel at 30 frames/s:

This estimate excludes protocol overhead, intensity images and point-cloud output. If each point contains three 4-byte coordinates, the same image grid represents 3,686,400 bytes per frame, or about 111 MB/s at the example frame rate. That is about 885 Mbit/s before overhead. Check whether the SDK transmits depth images or expanded point clouds; the difference can dominate network demand.

Each startup step removes or tests a separate dependency. If the application still aborts, compare your image against the vendor's supported installation on bare metal. The camera SDK build mismatch troubleshooting guide covers related timeout and loading checks. For a 3D-specific version check, use the firmware and SDK alignment guide.

Checks before you ship the container

• Start the container on a clean machine, not only your development host, and confirm it finds the scanner without manual steps.
• Restart the host and confirm the container reconnects; use the camera feature write-protect errors after reconnection guide if feature access changes after reconnecting.
• Verify the scanner's power and cabling separately if you see black or empty frames. The USB checks in depth camera black image troubleshooting and multiple USB depth cameras on Linux are relevant when the scanner connects over USB.
• Record the image digest and SDK version together, so a later rebuild cannot silently change either.
• Measure connection time, sustained frame rate and dropped frames with the full processing workload running. A successful discovery test does not establish acquisition reliability.

When the usual answer is wrong

Host networking can remove a bridge-related discovery obstacle, but it does not make link-local mDNS cross routed subnet boundaries. If the scanner and host are separated, use a permitted network arrangement, an approved discovery gateway, or documented direct-IP connection. Direct connection also needs the acquisition ports and return path to work.

Likewise, a failure that appears only under load does not clear the container or SDK of responsibility. Compare host and container performance while checking CPU use, memory pressure, container resource limits, packet loss and link settings. Change one variable at a time so you can identify the limiting layer.

Quick checklist

• Working directory or path variable set so the resource folder resolves.
• Required runtime libraries installed; documented headless API used where available.
• Discovery client connected to its daemon, with the correct network visibility.
• Host networking or discovery reflection reviewed for isolation and security implications.
• Scanner reachable by fixed IP from inside the container, if direct connection is supported.
• Scanner traffic separated from the plant LAN where practical.
• Image digest and SDK version logged at deployment.
• Acquisition tested after reboot and under the expected processing load.

If you are specifying the host for a new cell, the 3D sensors category lists the scanner families, and the vision controllers category covers multi-port hosts. To match a controller to a scanner pipeline end to end, start with the system configurator, or use the contact page for a review of your container and network design before you order.