Repository navigation
Description
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
-
Child Process Handshake Race Condition (
MeasureManager::waitForStarted):
Upon launching,OpenStudioAppspawns a child subprocess (openstudio measure -s <random_port>) to serve as a local HTTP micro-server for Ruby/Python measures. Simultaneously, a worker thread invokesMeasureManager::waitForStarted(10000), which actively pollshttp://localhost:<port>/in a tightprocessEvents()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. -
The "Delete Library" Trap (Re-entrant Event Loop Bug):
Users often try deletingoffice_default.osmorhvac_library.osmbased 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, causingResultStoreBase::clear<bool>()to consume and wipe the result of theMeasureManagerwatcher, leaving the wait dialog permanently stuck on screen. -
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-runningopenstudio measureprocess,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/OpenStudioAppThe 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
OpenStudioAppwindows. 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.0library 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.shHow to use it:
- Open Finder > Applications (or use Spotlight / Launchpad).
- Double-click
OpenStudio (Custom Launcher)(you can also pin it to your Dock). - The interface opens smoothly in ~1-2 seconds.
- Need to compare two models? Double-click the launcher again to open a second instance.
- Once you quit OpenStudio (
Cmd+Q), the background server process terminates automatically.
Activity
macumber commentedon Nov 12, 2026
Thanks @Christophe-Geneves, we will take a look at this