Skip to content

Startup hang on "Loading Library Files" on macOS (Apple Silicon): MeasureManager child process race condition & workaround #899

Open

Description

@Christophe-Geneves

ISSUE WAS DIAGNOSED AND A WORKAROUND FOUND WITH GOOGLE GEMINI


[Solution] OpenStudio Application Startup Freeze on "Loading Library Files" (macOS / Apple Silicon): Root Cause & Automated Multi-Instance Launcher

Problem Description

On macOS (specifically Apple Silicon M1–M5 chips on macOS Sonoma, Sequoia, and newer), launching OpenStudio Application (v1.10.x, v1.11.x) frequently leads to an indefinite hang on the initial splash screen:

Loading Library Files
(Manage library files in Preferences->Change default libraries)
Translation From version 3.11.0 to 3.11.0: .../office_default.osm

The application becomes unresponsive, the main editor never displays, and pressing Cmd+Q does nothing (requiring force-quit via Activity Monitor or Terminal).


Root Cause Analysis

  1. Child Process Handshake Race Condition (MeasureManager::waitForStarted):
    Upon launching, OpenStudioApp spawns a child subprocess (openstudio measure -s <random_port>) to serve as a local HTTP micro-server for Ruby/Python measures. Simultaneously, a worker thread invokes MeasureManager::waitForStarted(10000), which actively polls http://localhost:<port>/ in a tight processEvents() loop. On modern macOS architectures (Apple Silicon process scheduling and local socket sandboxing), the socket polling loop frequently deadlocks before the Ruby WEBrick server has finished binding to the port.

  2. The "Delete Library" Trap (Re-entrant Event Loop Bug):
    Users often try deleting office_default.osm or hvac_library.osm based on outdated forum tips. Doing so triggers a second bug: buildCompLibraries() fails instantaneously, displaying modal warning dialogs (showFailedLibraryDialog()). The nested modal Qt event loop re-dispatches queued signals re-entrantly, causing ResultStoreBase::clear<bool>() to consume and wipe the result of the MeasureManager watcher, leaving the wait dialog permanently stuck on screen.

  3. The Built-in Bypass:
    The OpenStudio codebase includes an environment variable:
    OPENSTUDIO_APPLICATION_USE_LOCAL_MEASURE_MANAGER_PORT=<port>
    When this variable is set and points to an already-running openstudio measure process, MeasureManager::waitForStarted() succeeds in < 1 ms, completely avoiding the subprocess spawning deadlock.


Quick 2-Line Verification (Terminal)

Before building the automated launcher, you can verify this fix immediately in your Terminal:

# 1. Start the measure server on a fixed local port in the background
/Applications/OpenStudioApplication-1.11.1/OpenStudioApp.app/Contents/MacOS/openstudio measure -s 50436 &

# 2. Launch OpenStudioApp pointing to that port
OPENSTUDIO_APPLICATION_USE_LOCAL_MEASURE_MANAGER_PORT=50436 /Applications/OpenStudioApplication-1.11.1/OpenStudioApp.app/Contents/MacOS/OpenStudioApp

The main OpenStudio interface will load immediately without freezing.


Complete Solution: Automated "On-Demand" Launcher App

Running background commands in the terminal every time is not convenient. The script below generates a standalone native macOS application bundle: OpenStudio (Custom Launcher).app in /Applications.

Features of this launcher:

  • Zero Background Footprint: Starts the local server only when you open the app.
  • Smart Auto-Shutdown: A lightweight watchdog monitors active OpenStudioApp windows. Once the last instance is closed, it automatically terminates the background Ruby server (0% CPU, 0 MB RAM left behind).
  • Multi-Instance Support: Double-clicking the launcher again opens a new, independent OpenStudio window sharing the same local port.
  • Fail-Safe Recovery: Automatically recreates clean standard 3.11.0 library models if they were deleted or corrupted during earlier troubleshooting.

Step-by-Step Installation

Copy and paste the following block into your macOS Terminal and hit Enter:

cat << 'EOF' > /tmp/create_openstudio_launcher.sh
#!/usr/bin/env bash
set -e

# Adjust version directory if necessary
APP_DIR=$(ls -d /Applications/OpenStudioApplication-*/OpenStudioApp.app 2>/dev/null | sort -V | tail -n 1)

if [ -z "$APP_DIR" ]; then
    echo "Error: OpenStudioApp.app not found in /Applications."
    exit 1
fi

LAUNCHER_NAME="OpenStudio (Custom Launcher).app"
TARGET_DIR="/Applications/$LAUNCHER_NAME"

echo "Creating $LAUNCHER_NAME using base: $APP_DIR..."

rm -rf "$TARGET_DIR"
mkdir -p "$TARGET_DIR/Contents/MacOS"
mkdir -p "$TARGET_DIR/Contents/Resources"

# 1. Copy original icon
if [ -f "$APP_DIR/Contents/Resources/os.icns" ]; then
    cp "$APP_DIR/Contents/Resources/os.icns" "$TARGET_DIR/Contents/Resources/os.icns"
fi

# 2. Write Info.plist
cat << PLIST_EOF > "$TARGET_DIR/Contents/Info.plist"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDisplayName</key>
    <string>OpenStudio (Custom Launcher)</string>
    <key>CFBundleExecutable</key>
    <string>launcher</string>
    <key>CFBundleIconFile</key>
    <string>os.icns</string>
    <key>CFBundleIdentifier</key>
    <string>org.openstudio.customlauncher</string>
    <key>CFBundleName</key>
    <string>OpenStudio (Custom Launcher)</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>LSUIElement</key>
    <true/>
</dict>
</plist>
PLIST_EOF

# 3. Write Watchdog Script (Auto-shutdown when all instances are closed)
cat << 'WATCHDOG_EOF' > "$TARGET_DIR/Contents/MacOS/watchdog.sh"
#!/usr/bin/env bash
sleep 4
while pgrep -x "OpenStudioApp" > /dev/null 2>&1; do
    sleep 2
done
PORT=50436
SERVER_PID=$(lsof -t -i :$PORT 2>/dev/null)
if [ -n "$SERVER_PID" ]; then
    kill "$SERVER_PID" 2>/dev/null || true
fi
WATCHDOG_EOF

# 4. Write Main Launcher Executable
cat << LAUNCHER_EOF > "$TARGET_DIR/Contents/MacOS/launcher"
#!/usr/bin/env bash
DIR="\$(cd "\$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
PORT=50436
OS_CLI="$APP_DIR/Contents/MacOS/openstudio"
OS_APP="$APP_DIR/Contents/MacOS/OpenStudioApp"
DEFAULT_LIB_DIR="$APP_DIR/Contents/Resources/default"

# Restore default libraries if missing
if [ ! -s "\$DEFAULT_LIB_DIR/hvac_library.osm" ] || [ ! -s "\$DEFAULT_LIB_DIR/office_default.osm" ]; then
    mkdir -p "\$DEFAULT_LIB_DIR"
    "\$OS_CLI" -e "m = OpenStudio::Model::Model.new; m.save('\$DEFAULT_LIB_DIR/hvac_library.osm', true); m.save('\$DEFAULT_LIB_DIR/office_default.osm', true)" >/dev/null 2>&1
fi

# Start local Measure Manager server if not already running
if ! lsof -i :\$PORT >/dev/null 2>&1; then
    "\$OS_CLI" measure -s \$PORT > /tmp/openstudio_measure.log 2>&1 &
    for i in {1..15}; do
        if lsof -i :\$PORT >/dev/null 2>&1; then
            break
        fi
        sleep 0.2
    done
fi

# Start watchdog monitor if not already active
if ! pgrep -f "\$DIR/watchdog.sh" > /dev/null 2>&1; then
    nohup /bin/bash "\$DIR/watchdog.sh" > /dev/null 2>&1 &
fi

# Launch OpenStudio instance
export OPENSTUDIO_APPLICATION_USE_LOCAL_MEASURE_MANAGER_PORT=\$PORT
nohup "\$OS_APP" "\$@" > /dev/null 2>&1 &
exit 0
LAUNCHER_EOF

# 5. Set executable permissions and remove quarantine
chmod +x "$TARGET_DIR/Contents/MacOS/launcher"
chmod +x "$TARGET_DIR/Contents/MacOS/watchdog.sh"
xattr -cr "$TARGET_DIR" 2>/dev/null || true

echo "SUCCESS: $LAUNCHER_NAME installed in /Applications."
EOF
bash /tmp/create_openstudio_launcher.sh && rm /tmp/create_openstudio_launcher.sh

How to use it:

  1. Open Finder > Applications (or use Spotlight / Launchpad).
  2. Double-click OpenStudio (Custom Launcher) (you can also pin it to your Dock).
  3. The interface opens smoothly in ~1-2 seconds.
  4. Need to compare two models? Double-click the launcher again to open a second instance.
  5. Once you quit OpenStudio (Cmd+Q), the background server process terminates automatically.

Activity

  1. added
    TriageIssue needs to be assessed and labeled, further information on reported might be needed
    on Nov 11, 2026
  2. macumber commented on Nov 12, 2026

    @macumber
    Collaborator

    Thanks @Christophe-Geneves, we will take a look at this

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    TriageIssue needs to be assessed and labeled, further information on reported might be needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions