freecad-robust-mcp-fc111/dev-notes/freecad-gui-hang-bug-report.md

FreeCAD GUI Binary Hangs in Headless CI Environments Without Window Manager

Bug Report: github.com/FreeCAD/FreeCAD/issues/26817

---

TL;DR (GitHub Issue Version)

Bug: freecad --version hangs indefinitely when run with Xvfb but without a window manager. freecadcmd --version works fine.

Environment: FreeCAD 1.0.2 AppImage, Ubuntu 22.04, Xvfb

Reproduce:

Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
./FreeCAD.AppImage --appimage-extract
./squashfs-root/AppRun freecad --version  # HANGS
./squashfs-root/AppRun freecadcmd --version  # Works

Cause: FreeCAD GUI requires window manager events to display any window (including the --version dialog box). Without a WM, Qt waits indefinitely for ConfigureNotify/Expose events that never arrive.

Note: Unlike most CLI tools, freecad --version displays a GUI dialog, not console output.

Workaround: Run openbox & before FreeCAD, or use freecadcmd for headless operations.

---

Detailed Report

Summary

The FreeCAD GUI binary (freecad) hangs indefinitely during Qt initialization when run in a headless environment with Xvfb but without a window manager. This affects all command-line operations including freecad --version and freecad --help. The headless binary (freecadcmd) works correctly in the same environment.

Environment

• FreeCAD versions tested: 1.0.2 (stable), 1.1.0 (weekly-2025.09.03)
• Platform: Linux (Ubuntu 22.04, both x86_64 and aarch64)
• AppImage: FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage
• Display: Xvfb virtual framebuffer (:99, 1920x1080x24)
• Qt platform: xcb
• Context: GitHub Actions CI, Docker containers

Steps to Reproduce

Easiest reproduction using Docker (hangs)

This one-liner reproduces the bug in an isolated container:

# Run this on any system with Docker installed (Linux, macOS, Windows)
# Automatically selects the correct AppImage for your architecture (x86_64 or aarch64)
docker run --rm -it ubuntu:22.04 bash -c '
  apt-get update && apt-get install -y xvfb curl libfuse2 libgl1 libegl1 openbox >/dev/null 2>&1
  cd /tmp
  ARCH=$(uname -m)
  if [ "$ARCH" = "aarch64" ]; then
    APPIMAGE="FreeCAD_1.0.2-conda-Linux-aarch64-py311.AppImage"
  else
    APPIMAGE="FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage"
  fi
  echo "Downloading FreeCAD AppImage for $ARCH..."
  curl -sLO "https://github.com/FreeCAD/FreeCAD/releases/download/1.0.2/$APPIMAGE"
  chmod +x "$APPIMAGE"
  echo "Extracting AppImage..."
  ./"$APPIMAGE" --appimage-extract > /dev/null
  ls -la /tmp/squashfs-root/AppRun
  export XDG_RUNTIME_DIR=/tmp/runtime-root
  echo "Starting freecadcmd with xvfb-run (should work fine)..."
  xvfb-run -a /tmp/squashfs-root/AppRun freecadcmd --version || echo "This should have worked"
  echo "Starting FreeCAD with xvfb-run (will hang without window manager)..."
  timeout 10 xvfb-run -a /tmp/squashfs-root/AppRun freecad --version || echo "HUNG as expected (timeout after 10s)"
  Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp &
  sleep 2
  export DISPLAY=:99
  openbox &
  xvfb-run -a /tmp/squashfs-root/AppRun freecad --version
'

Simplest reproduction using xvfb-run (hangs)

# Download FreeCAD AppImage
curl -LO "https://github.com/FreeCAD/FreeCAD/releases/download/1.0.2/FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage"
chmod +x FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage

# Extract AppImage (required because xvfb-run doesn't work well with FUSE)
./FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage --appimage-extract

# This hangs indefinitely - xvfb-run provides Xvfb but no window manager
xvfb-run --auto-servernum ./squashfs-root/AppRun freecad --version

The xvfb-run wrapper is commonly used in CI environments to run GUI applications headlessly. It starts Xvfb automatically, but does not start a window manager, causing FreeCAD to hang.

Manual Xvfb reproduction (hangs)

# Start Xvfb without a window manager
Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp &
sleep 2
export DISPLAY=:99
export QT_QPA_PLATFORM=xcb

# Extract and run FreeCAD AppImage
./FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage --appimage-extract
./squashfs-root/AppRun freecad --version  # HANGS INDEFINITELY

Variants that also hang

# All of these hang:
./squashfs-root/AppRun freecad --help
./squashfs-root/AppRun freecad --version
./squashfs-root/AppRun freecad -c "print('hello')"
QT_QPA_PLATFORM=offscreen ./squashfs-root/AppRun freecad --version
QT_QPA_PLATFORM=minimal ./squashfs-root/AppRun freecad --version

What works correctly

# Headless binary works fine:
./squashfs-root/AppRun freecadcmd --version  # Works immediately
./squashfs-root/AppRun freecadcmd -c "import FreeCAD; print(FreeCAD.Version())"  # Works

Expected Behavior

FreeCAD GUI should work in headless CI environments with just Xvfb, allowing:

1. Display of version/help dialogs (FreeCAD uses GUI dialogs, not console output)
2. Execution of Python scripts
3. Basic GUI operations for automated testing

Note: Unlike most CLI tools, freecad --version and freecad --help display GUI dialog boxes rather than printing to the console. This is by design, but it means they require a functioning GUI environment.

Actual Behavior

The freecad binary:

1. Connects to X11 display successfully
2. Initializes Qt's QApplication
3. Attempts to create/display a window (version dialog, main window, etc.)
4. Waits indefinitely for X11 window manager events that never arrive
5. Hangs before the dialog/window can be displayed

Technical Analysis

Process State During Hang

Using strace and /proc inspection, we found:

Process state: S (sleeping)
Threads: 2
Thread 1 (main): waiting in do_sys_poll on eventfd
Thread 2 (X11 reader): waiting in do_sys_poll on X11 socket

Strace Output

The final syscalls before the hang show both threads blocked on ppoll():

# Thread 21 (main Qt event loop) - waiting on eventfd with 30s timeout
[pid 21] ppoll([{fd=6, events=POLLIN}], 1, {tv_sec=29, tv_nsec=541000000}, NULL, 8

# Thread 22 (X11 reader) - waiting on X11 socket indefinitely
[pid 22] ppoll([{fd=4, events=POLLIN}], 1, NULL, NULL, 0 <unfinished ...>

The file descriptors are:

• fd 4: X11 socket connection (successfully established)
• fd 6: eventfd for Qt thread synchronization

Root Cause

FreeCAD's GUI requires window manager events to display any window or dialog (including the --version dialog). In a bare Xvfb environment without a window manager:

1. FreeCAD creates a window and waits for it to be mapped/configured
2. No window manager means no ConfigureNotify, Expose, or MapNotify events
3. Qt's event loop waits for these events before the window can be displayed
4. The main thread blocks waiting for signals from the X11 reader thread
5. The X11 reader thread blocks waiting for X11 events that never arrive
6. Deadlock: both threads wait indefinitely for events that will never come

Why freecadcmd Works

The freecadcmd binary does not initialize Qt's GUI components, so it never enters this blocking state.

Workaround

Running a lightweight window manager (like openbox) alongside Xvfb resolves the issue:

# Start Xvfb
Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp &
sleep 2
export DISPLAY=:99

# Start a window manager (this is the key fix)
openbox &
sleep 1

# Now FreeCAD GUI works
./squashfs-root/AppRun freecad --version  # Works!

Additionally, sending synthetic X11 events with xdotool can help:

# In a loop while FreeCAD starts:
xdotool mousemove 500 500 click 1 key Escape

Suggested Fixes

Several approaches could improve FreeCAD's headless CI compatibility:

Option 1: Add timeout/fallback for window manager events

FreeCAD could detect when no window manager responds within a reasonable timeout (e.g., 5 seconds) and either:

• Fall back to a minimal mode
• Exit with a clear error message instead of hanging indefinitely
• Use QT_QPA_PLATFORM=offscreen automatically when no WM is detected

Option 2: Console output for --version/--help (CI-friendly)

For CI environments, having --version and --help output to console (like most CLI tools) would be helpful. This could be:

• A separate flag like --version-console
• Automatic when DISPLAY is not set or in a detected CI environment
• Controlled by an environment variable

Option 3: Document the window manager requirement

At minimum, clearly document that the FreeCAD GUI binary requires a window manager (not just Xvfb) for any operation, including --version.

Impact

This bug affects:

• CI/CD pipelines using FreeCAD in headless environments
• Docker containers running FreeCAD without a display manager
• Automated testing of FreeCAD-based applications
• Server-side rendering or batch processing with GUI features

The workaround (adding openbox) increases container size and complexity for CI environments.

Additional Context

Test Script

Here's a complete test script that demonstrates both the bug and the workaround:

#!/bin/bash
set -e

# Setup
apt-get update && apt-get install -y xvfb openbox xdotool curl
curl -LO "https://github.com/FreeCAD/FreeCAD/releases/download/1.0.2/FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage"
chmod +x FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage
./FreeCAD_1.0.2-conda-Linux-x86_64-py311.AppImage --appimage-extract

export DISPLAY=:99
Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp &
sleep 2

echo "=== Test 1: Without window manager (will hang) ==="
timeout 10 ./squashfs-root/AppRun freecad --version || echo "HUNG as expected"

echo "=== Test 2: With window manager (works) ==="
openbox &
sleep 1
timeout 10 ./squashfs-root/AppRun freecad --version && echo "SUCCESS"

Related

• This may be related to how FreeCAD integrates with PySide6/Qt6
• The freecadcmd binary correctly avoids this issue by not initializing GUI
• Other Qt applications (like qmlscene --help) typically handle this correctly

System Information

FreeCAD 1.0.2, Libs: 1.0.2R39319 (Git)
OS: Ubuntu 22.04 (Docker/GitHub Actions)
Python: 3.11.13 (conda-forge)
Qt: 6.x (bundled in AppImage)