Troubleshooting

Device Not Detected

Device doesn't appear in the dashboard

• Verify the device is connected via USB: ./bin/go-ios list --details --pretty
• Ensure the device is trusted/paired with the Mac (tap "Trust" on the device when prompted)
• On iOS 16+, ensure Developer Mode is enabled (Settings → Privacy & Security → Developer Mode)
• Check the Provider logs for connection errors
• Try unplugging and reconnecting the USB cable

Device connects then disconnects repeatedly

• Try a different USB cable (use Apple-branded or MFi-certified cables)
• Try a different USB port
• Check if another process is using the device (Xcode, Instruments, etc.)
• Restart the device

Agent Won't Start / XCTest Launch Failures

CFA Agent fails to launch

• Verify the apps are properly signed (see Signing Guide)
• Trust the developer certificate on the device: Settings → General → VPN & Device Management
• Ensure the device has internet access (required for app verification on iOS 17+)
• Check that the provisioning profile includes this device's UDID
• Try manually launching the app from the device home screen to see if iOS displays an error

XCTest runner crashes immediately

• Ensure the Xcode version matches the iOS version on the device
• Check for Xcode command-line tools: xcode-select -p
• Clear the Xcode derived data: rm -rf ~/Library/Developer/Xcode/DerivedData/*
• Restart the device and try again

Video Streaming Issues

No video in the dashboard

• Verify VidStream is properly signed and installed
• Check the video display mode in server config: "videoDisplay": "vidstream"
• Try switching to screenshot mode: "videoDisplay": "screenshot"
• Check if the broadcast extension launched (visible in Provider logs)
• Ensure the video port range is not blocked by firewalls

Video is laggy or low quality

• Check the network between the Provider Mac and the Server
• Reduce video resolution in the stream configuration
• Verify the Mac has adequate CPU resources (each device stream requires some processing)
• For screenshot mode, reduce screenshot quality via the API

iOS 17+ Tunnel Problems

Tunnel fails to establish

• For "internal": Ensure remotedtool and utunuds are present and set to suid root. Early iOS 17 firmware versions may not support this method — try "pmd3" instead.
• For "pmd3": Ensure Python 3 and pymobiledevice3 are installed. Check that the virtualenv is active or PYTHONPATH is set correctly.
• For "tunneld": Ensure the pymobiledevice3 tunneld daemon is running (sudo python3 -m pymobiledevice3 remote tunneld) before starting the Provider.
• Restart the device — some tunnel issues are resolved by a clean restart
• Try a different tunnel method to isolate the issue

Tunnel works intermittently

• Check USB cable quality — intermittent connections cause tunnel failures
• Disable and re-enable Developer Mode on the device
• Update to the latest ControlFloor Provider, which includes tunnel stability fixes

Signing and Provisioning Errors

"No signing identity found"

• Open Keychain Access and verify your Apple Development certificate is present
• Run security find-identity -v -p codesigning to list valid signing identities
• Ensure the certificate is not expired

"App won't install" or "Untrusted Developer"

• On the device: Settings → General → VPN & Device Management → Trust your developer certificate
• Verify the device UDID is in your provisioning profile
• Regenerate the provisioning profile if you recently added the device

Server Connection Issues

Can't access the web dashboard

• Verify the server is running: check for the process or log output
• Check the listen address in config — ":8080" listens on all interfaces, "localhost:8080" only on localhost
• If using HTTPS with a self-signed cert, accept the browser's certificate warning
• Check firewall rules: port 8080 (or your configured port) must be open

Provider can't connect to server

• Verify the controlfloor.host in the Provider config matches the server address
• For self-signed certs, ensure selfSigned: true is set in Provider config
• Check network connectivity between the Provider Mac and the Server
• Re-register the Provider if credentials may have changed

Keyboard Automation Issues

Text input doesn't work or types wrong characters

• Ensure only two keyboards are installed on the device: one Western layout + Emoji
• Run device initialization to configure keyboard settings
• Disable auto-correct, auto-capitalization, and smart punctuation on the device
• Check that the keyboard layout matches the expected locale
• Use tapText instead of typeText for secure fields

Keyboard doesn't appear

• Tap on a text field first to bring up the keyboard
• Check if a hardware keyboard is connected (disconnect it)
• Settings → General → Keyboard → ensure "Enable Dictation" is off if it interferes

Performance Tuning

Automation commands are slow

• Reduce the delay between commands: device.setDelay(0.1)
• Use element search with narrow filters (specify elementTypes to reduce search scope)
• Use maxDepth to limit element tree traversal depth
• For screenshot-based operations, use JPEG format with lower quality for speed

Multiple devices cause slowdowns

• Check Mac CPU and memory usage — each device requires some resources
• Consider distributing devices across multiple Provider Macs
• Use runner mode for more efficient multi-device management
• Ensure USB hubs are powered (unpowered hubs can cause bandwidth issues)