Haptix/Docs

Troubleshooting

Common issues and how to fix them.

Camera permission required

Symptom: start_session returns cameraPermissionDenied or cameraPermissionRestricted.

Cause: As of v1.4.7, Haptix requires macOS Camera permission. CoreMediaIO uses it to read the iOS device screen over USB. There is no degraded path — sessions refuse to start without it.

Fix:

haptix setup

haptix setup opens System Settings to the right pane and waits for the toggle. Or open it manually: System Settings → Privacy & Security → Camera → enable Haptix or your terminal app, then:

haptix stop && haptix start

The TCC grant belongs to the haptix binary itself (not Terminal, not the Mac app).

No license key configured

Symptom: start_session returns a licensing error, or haptix license reports "No license key configured".

Fix:

# Free trial — one per machine, no signup
haptix trial

# Or activate a purchased key
haptix license HPTX-XXXX-XXXX-XXXX

Trial keys (HPTX-TRIAL-XXXX-XXXX) work identically to purchased keys for the trial window. If haptix trial returns already_trialed, this machine has used its free trial — purchase at /plans.

Device not discovered

Symptom: haptix devices shows nothing, or start_session reports "no devices found."

Fixes:

  1. Full Xcode installed + selected — Command Line Tools alone are not enough. Confirm:

    xcrun --version
xcodebuild -version
xcrun devicectl --version

    If Xcode is installed but not selected, run:

    sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch

  2. USB cable supports data — Some cables are charge-only. Try a different cable or USB port.

  3. Device unlocked + trusted — When you first connect a device, iOS asks "Trust This Computer?" Tap Trust and enter your unlock code.

  4. Developer Mode + UI Automation — Settings → Privacy & Security → Developer Mode (on; reboots once); Settings → Developer → Enable UI Automation (on).

  5. System sees the device — Run xcrun devicectl list devices. If the system sees it but haptix devices is empty, restart the daemon: launchctl kickstart -k gui/$(id -u)/dev.haptix.server.

Agent crashes ~7 seconds after start_session

Symptom: The on-device agent connects, then exits with "connection was invalidated" a few seconds later.

Cause: A USB channel renegotiation race that affected versions before v1.4.7.

Fix:

curl -fsSL https://get.haptix.dev/install.sh | bash

v1.4.7 reordered CoreMediaIO startup before agent deploy and waits for the first frame. The race is gone.

Agent can't connect to MCP server

Symptom: Your AI agent reports it can't reach the Haptix MCP server.

Fixes:

  1. Daemon running — haptix status should report running. If not, haptix start.
  2. Correct URL — The endpoint is http://localhost:4278/mcp. Check your agent's config for typos. If you have an older config using /sse, update it to /mcp.
  3. Port conflict — If something else is using port 4278, the daemon won't start. lsof -i :4278 to check.
  4. Config file location — See MCP Setup for the exact path per agent.
  5. Restart agent — Some agents (Cursor, VS Code) require a restart or window reload after adding MCP config.

Taps not working on specific controls

Symptom: Taps work on some elements but not others.

Possible causes:

  1. Context menus — UIContextMenuInteraction / SwiftUI .contextMenu items don't accept synthetic taps. See Compatibility.
  2. System-presented UI — Alerts, action sheets, and share sheets may reject synthetic touches. See Compatibility.
  3. Menu-style pickers — SwiftUI Picker with .menu style uses context menus internally. See Compatibility.
  4. Keyboard covering element — Dismiss the keyboard first (drag from content area down past the screen bottom).
  5. Element off-screen — Use scroll to bring it into the viewport.

Gestures not working as expected

Symptom: Swipe, drag, pinch, or rotate doesn't produce the expected result.

Possible causes:

  1. Swipe on pickers — Use small swipe movements directly on the picker wheel column. Vertical full-screen swipes get redirected to programmatic scrolling.
  2. Use scroll for page navigation — For up/down/left/right page scrolling, use scroll rather than swipe. It's more reliable.
  3. Drag-and-drop (long-press-then-drag) — System-level drag-and-drop currently doesn't work via synthetic touches. Reorderable lists do work via drag. See Compatibility.

Pinch, rotate, and drag now work as of v1.4.x via IOHIDEvent multi-touch synthesis.

"iOS Simulator" support

Haptix does not support the iOS Simulator. CoreMediaIO + USB are macOS-side requirements that the Simulator doesn't expose. Use a physical iPhone or iPad on iOS 18+ connected via USB.

Slow first interaction

Symptom: The first session per daemon lifetime takes ~3 seconds longer to start.

Cause: CoreMediaIO needs to warm up and deliver its first frame before the on-device agent is deployed. This is a v1.4.7 design — it eliminates the older "agent crashes ~7s after start" race.

Fix: Expected behavior. Subsequent sessions are unchanged. If you want to skip the warmup cost between sessions, leave the daemon running and reuse the same device.

App crashes on launch with HaptixKit

Possible causes:

  1. Release build — If HaptixKit ends up in a Release build and the app can't find development frameworks, it may crash. Always wrap Haptix.start(...) in #if DEBUG and link only the Debug configuration.
  2. iOS version — HaptixKit requires iOS 18.0+. Earlier versions will crash on import.

Screenshots are blank or black

Possible causes:

  1. App in background — The app must be in the foreground for screenshots to capture content.
  2. Secure content — Some system UI (password fields, certain system sheets) renders as black for security.
  3. GPU rendering — Rarely, Metal-rendered content may not capture correctly. Try mode: "full" instead of mode: "app".

Still stuck?

If none of the above resolves your issue:

  • Email support@haptix.dev with:

    • Your macOS version and device/iOS version
    • The Haptix version (haptix --version or haptix status)
    • What you tried and what happened
    • Any error messages from the Xcode console or haptix logs --last 200

  • Check the Compatibility page for known issues with specific controls or gestures.