ios-simulator/references/TROUBLESHOOTING.md

Troubleshooting

xcrun: error: unable to find utility "simctl", not a developer tool or in PATH

• Ensure Xcode / Command Line Tools are installed.
• Ensure the correct developer dir is selected:
  • xcode-select -p to view
  • sudo xcode-select -s /Applications/Xcode.app (or your Xcode path)
• Run first-launch component install:
  • xcodebuild -runFirstLaunch

No simulators listed / missing runtimes

• Open Xcode → Settings/Preferences → Platforms (or Components) and install an iOS Simulator runtime.
• Then re-run:
  • node {baseDir}/scripts/ios-sim.mjs list --full

idb not found

This skill can still do simctl operations, but UI automation requires idb.

Install:

brew tap facebook/fb
brew install idb-companion
python3 -m pip install --upgrade fb-idb

idb can’t see the simulator / empty output

• Make sure the simulator is booted:
  • node {baseDir}/scripts/ios-sim.mjs boot --wait
• Try running idb directly:
  • idb ui describe-all --udid <UDID>
• If you have multiple simulators booted, always pass --udid.

UI element not found via ui tap --query ...

• The accessibility label might differ from visible text.
• Use:
  • node {baseDir}/scripts/ios-sim.mjs ui summary --limit 50
  • or node {baseDir}/scripts/ios-sim.mjs ui tree and search the JSON for AXLabel / title.
• If there are multiple matches, narrow the query (e.g. “Log in” vs “Log”).

Hanzo Bot gateway not on macOS

You must run commands on a macOS environment (gateway or node) where Xcode tools exist.

Use Hanzo Bot’s node execution so the command runs on the macOS node.