Skip to content

Docker

Troubleshooting Banner

Jetson Xavier NX

ubuntu 24.04

Docker Troubleshooting#

Drivers containers exits/restarts immediately#

Cause: The launch command failed, most commonly a missing or mismatched device path, or a misconfigured launch argument.

docker compose logs base_lidar_driver

or

docker logs base_lidar_driver

Check that the device paths exist on the host:

ls /dev/micipsa/

If devices are missing, make sure udev rules are installed and reload them:

sudo udevadm control --reload-rules && sudo udevadm trigger

Camera container starts but no image topics appears#

Cause: Device nodes exist but the RealSense SDK cannot open the camera, often a permissions issue or a wrong video device mapping.

docker exec -it front_camera_driver bash
source /ros2_ws/install/setup.bash
ros2 node list              # Is realsense2_camera present?
ros2 topic list             # Are /color/image_raw etc. published?
v4l2-ctl --list-devices     # Check which /dev/videoN devices are visible inside the container

Verify that the devices: mapping in the Compose file matches the actual host device assignments for the RealSense streams.

No ROS 2 nodes visible from the host#

Cause: DDS discovery is failing, typically a network interface mismatch or missing network_mode: host.

  1. Confirm network_mode: host is set for all containers
  2. Confirm cyclonedds.xml is binding to the correct network interface
  3. Confirm ROS_DOMAIN_ID matches on both the host and inside containers

colcon build fails during image build#

Cause: Usually a missing dependency or wrong build context.

  1. Ensure you are building from the repository root (see Build Image)
  2. Check rosdep output in the build log for unresolved packages
  3. Try --no-cache to rule out stale layers:
docker build --no-cache \
  -f infra/docker/actuation/Dockerfile \
  -t micipsa/actuation:jazzy-v1.0.0 \
  .

Nodes run but container unhealthy#

Cause: Usually system is under heavy load

A common mistake is using DDS-based commands in healthchecks:

# ❌ Fragile ddepends on DDS discovery succeeding under load
test: ["CMD", "bash", "-c", "ros2 topic info /tf_static --no-daemon"]

ros2 topic info performs DDS peer discovery every time it runs. When the system is under heavy load (SLAM + Navigation publishing simultaneously), discovery can time out, causing healthy containers to be marked unhealthy.

Prefer process-level checks for stateless publishers:

# ✅ Fast, local, unaffected by DDS load
test: ["CMD", "bash", "-c", "pgrep -f robot_state_publisher > /dev/null"]

Note

Healthchecks run continuously for the entire container lifetime, not just at startup. depends_on: condition: service_healthy only gates the startup chain, it does not restart dependents if a container later becomes unhealthy.