Troubleshoot Simulation Issues

Simulation Failed

1. Check status and logs:

get_run_status(run_id=...)
get_run_logs(run_id=..., stream="energyplus")   # stream="openstudio" (default) or "energyplus"

2. Common fatal errors and fixes:

Error pattern	Cause	Fix
No weather file	Missing or wrong EPW path	change_building_location(weather_file="/inputs/...")
No SizingPeriod	Missing design days	change_building_location (loads DDY automatically)
Could not find the stat file	EPW missing companion .stat/.ddy	EPW needs .stat + .ddy files alongside with same base filename
Node not connected	Broken HVAC loop	Check with get_air_loop_details / get_plant_loop_details
Surface has no vertices	Bad geometry	Check list_surfaces() for degenerate surfaces
Zone has no surfaces	Empty thermal zone	Zone needs spaces with geometry assigned
Due to limitations on Windows file path lengths ... less than 90 characters	MISLEADING — an openstudio-standards sizing run could not read/resolve the weather file (nothing to do with path length). The model's EPW reference points somewhere unreadable	Re-run change_building_location(weather_file=...) with a real EPW path so the reference is re-staged
Terminal unit not found on any ZoneTerminalUnitList	VRF terminals orphaned from the outdoor unit	Rebuild the system with add_vrf_system (older models may carry an incompatible FluidTemperatureControl outdoor unit)

Results Look Wrong

1. Check EUI range (typical commercial: 50-200 kBtu/ft2):

extract_summary_metrics(run_id=...)

2. Common causes of bad EUI:

EUI too high:

• Missing/wrong thermostat schedules → get_schedule_details, set_thermostat_schedules
• Oversized HVAC → extract_hvac_sizing to check autosizing
• High infiltration → list_model_objects(object_type="SpaceInfiltrationDesignFlowRate")

EUI too low:

• Missing internal loads → list_model_objects(object_type="People"), list_model_objects(object_type="Lights"), list_model_objects(object_type="ElectricEquipment")
• No HVAC (ideal air or missing) → list_air_loops, list_zone_hvac_equipment
• Wrong run period (partial year) → get_run_period

High unmet hours:

• Undersized equipment → extract_component_sizing
• Thermostat vs availability schedule conflict
• Missing plant loop equipment → get_plant_loop_details

3. Detailed diagnostics:

extract_zone_summary(run_id=...)          # per-zone temps and loads
extract_component_sizing(run_id=...)      # autosized values
query_timeseries(run_id=..., variable_name="Zone Mean Air Temperature",
    frequency="Hourly", key_value="Zone 1")

Measure Test / Apply Failed

test_measure and apply_measure failures return log_path, log_tail, exit_code, and crash_marker. log_tail is an excerpt; read the whole log first:

read_file(file_path="<log_path from the failure response>")

Signal	Cause	Fix
crash_marker = [BUG] Segmentation fault, error says SIGABRT/SIGSEGV	Native SDK crash inside the measure, usually remove() then addToNode on a node the removal deleted	Add the replacement component first, then remove the old one; re-run test_measure
crash_marker null, backtrace names measure.rb / measure.py	Ordinary Ruby/Python error in run_body	Fix the line shown; see "Verify SDK Methods" for NoMethodError
Measure run timed out	Measure loops or waits	Partial log at log_path; simplify the measure

Verify SDK Methods

If a measure fails due to nonexistent API methods:

search_api("CoilCoolingFourPipeBeam")              # list real setters/getters
search_api("BoilerHotWater", method_pattern="Efficiency")
# each entry is a signature: "setNominalThermalEfficiency(nominalThermalEfficiency) -> Boolean"
# "-> X, nil" = Optional (.get after .is_initialized); "-> ?" = unknown, probe first;
# "[static] " prefix = call on the class, not an instance

Quick Fixes

Problem	Tool
Add missing weather	change_building_location (sets EPW + DDY + climate zone)
Add missing HVAC	add_baseline_system
Remove broken objects	clean_unused_objects
Check model completeness	run_qaqc_checks
Inspect without simulating	inspect_osm_summary