From 25649c1f018fa5f6e19935895430445c5ea67ef0 Mon Sep 17 00:00:00 2001 From: Pavel Guzenfeld <67074795+PavelGuzenfeld@users.noreply.github.com> Date: Sun, 15 Mar 2026 23:19:23 +0200 Subject: [PATCH] Add troubleshooting entry for libunwind/libgcc_s exception handling conflict Signed-off-by: Pavel Guzenfeld <67074795+PavelGuzenfeld@users.noreply.github.com> --- .../troubleshooting/troubleshooting.rst | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/fastdds/troubleshooting/troubleshooting.rst b/docs/fastdds/troubleshooting/troubleshooting.rst index 6c88cf75d..5ad6285b0 100644 --- a/docs/fastdds/troubleshooting/troubleshooting.rst +++ b/docs/fastdds/troubleshooting/troubleshooting.rst @@ -49,3 +49,33 @@ issues. In consequence, discovery traffic can be increased during start up. If you are experiencing high load during discovery, try disabling the new feature. Please refer to :ref:`disable type propagation` to learn how to do it. + +* Applications that load **libunwind** at runtime (e.g., through profiling tools such as + ``gperftools``, ``heaptrack``, or sanitizer runtimes) may experience segmentation faults during + C++ exception handling within Fast DDS. This is caused by a symbol conflict between ``libunwind`` + and ``libgcc_s``: both export ``_Unwind_*`` symbols with incompatible internal layouts, and if + ``libunwind`` is resolved first, it interferes with the GCC exception-handling ABI. The crash + typically manifests as a ``SIGABRT`` or ``SIGSEGV`` inside the ``_Unwind_RaiseException`` call + chain. This is especially common in Docker containers where ``libunwind`` is pulled in + transitively by GStreamer or other multimedia frameworks. + + **Workaround**: ensure ``libgcc_s`` is loaded before ``libunwind`` by preloading it: + + .. code-block:: bash + + # Shell + export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libgcc_s.so.1 + + # Dockerfile + ENV LD_PRELOAD=/lib/x86_64-linux-gnu/libgcc_s.so.1 + + On ``aarch64`` systems, adjust the library path accordingly + (e.g., ``/usr/lib/aarch64-linux-gnu/libgcc_s.so.1``). + + .. note:: + + This is not a Fast DDS bug but a known Linux ecosystem issue affecting any C++ application + that uses exceptions when both unwinder implementations are loaded. See + `Ubuntu bug #1960005 `__ + and `LLVM issue #90041 `__ for upstream + discussions.