Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
95 lines (81 loc) · 3.89 KB

TROUBLESHOOTING.md

File metadata and controls

95 lines (81 loc) · 3.89 KB
Raw

iOS Simulator CLI - TROUBLESHOOTING

If you encounter errors or issues using this CLI, try the following troubleshooting steps before reporting a bug:

1. Prerequisites

  • macOS Only: This tool only works on macOS with Xcode and iOS simulators installed.
  • IDB Tool: Ensure Facebook IDB is installed and available in your PATH.
  • Node.js: Make sure Node.js is installed and up to date (for npm installs).

2. Installing IDB

The installation section in IDB is a little out of date. Since python environments are famously borked, here are some ways to install that are hopefully compatible with your existing python install.

Using Homebrew + pip

  1. Install Homebrew if you don't have it: 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Install Python (if not already installed): 
    brew install python
  3. Install idb using pip: 
    pip3 install --user fb-idb
  4. Ensure your user base binary directory is in your PATH (often ~/.local/bin): 
    export PATH="$HOME/.local/bin:$PATH"
# Add the above line to your ~/.zshrc or ~/.bash_profile for persistence
  5. Verify installation: 
    idb -h

Using asdf (Python version manager)

  1. Install asdf: 
    brew install asdf
  2. Add the Python plugin, install Python, set to global version (see asdf docs for set and global to do isolated installs): 
    asdf plugin add python
asdf install python latest
asdf global python latest
asdf set python <latest-version> -u
asdf reshim
  3. Install idb using pip: 
    python -m pip install --user fb-idb
  4. Ensure your user base binary directory is in your PATH (often ~/.local/bin): 
    export PATH="$HOME/.local/bin:$PATH"
# Add the above line to your ~/.zshrc or ~/.bash_profile for persistence
  5. Verify installation: 
    idb -h

3. Common Issues & Fixes

"No booted simulator found"

  • Open Xcode and boot an iOS simulator manually.
  • Run xcrun simctl list devices to verify a simulator is booted.

"idb: command not found" or IDB errors

  • Follow the install steps above for Homebrew + pip or asdf.
  • Ensure idb is in your PATH: try running idb -h in your terminal.
  • Set a custom path with IOS_SIMULATOR_CLI_IDB_PATH if needed.
  • On Apple Silicon Macs, install fb-idb with the system/Xcode Python (arm64), not Intel Homebrew Python: 
    /usr/bin/python3 -m pip install --user fb-idb
export IOS_SIMULATOR_CLI_IDB_PATH="$HOME/Library/Python/3.9/bin/idb"
  • If you see spawn idb EACCES or CoreSimulator couldn't be loaded because it doesn't contain a version for the current architecture, your idb is likely using an x86_64 Python while idb_companion needs arm64. Reinstall fb-idb with /usr/bin/python3 as shown above.

Permission or File Errors

  • Ensure you have permission to write to the output path (e.g., for screenshots or recordings).
  • Try using a path in your home directory or ~/Downloads.
  • Set IOS_SIMULATOR_CLI_DEFAULT_OUTPUT_DIR to a writable directory.

Simulator UI Not Responding

  • Restart the simulator and try again.
  • Quit and relaunch Xcode if needed.
  • Check dimensions of the simulator screen and adjust coordinates accordingly. Screenshots have 3x resolution and this may result in incorrect position of screen presses.

4. Still Stuck?

  • Check the README for setup and usage instructions.
  • If the problem persists, open an issue and include the error message and steps to reproduce.