Haptix/Docs

Troubleshooting

Common issues and how to fix them.

Start here: ask the daemon what's wrong

Before walking through individual entries, run the three diagnostic commands. Each one tells you what's wrong on its surface and what to try next:

haptix capture status        # screen-capture pipeline + device visibility
haptix permissions status    # Camera permission + iPhone prereqs
haptix devices refresh       # force-rediscover connected devices

If something's wrong, the human-readable output points you at the right fix. The entries below cover the cases those commands name.

Camera permission required

Symptom: start_session returns cameraPermissionDenied or cameraPermissionRestricted.

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

Fix:

haptix permissions fix       # walks through requesting or re-enabling Camera

If Camera was previously denied, permissions fix opens System Settings → Privacy & Security → Camera for you. Enable Haptix (or your terminal app) in the list, 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."

Fast path:

haptix devices refresh

If that comes back empty, work through these in order:

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

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

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

  4. Device added to your Apple Developer Team — at developer.apple.com → Account → Devices. Required before Haptix can install its on-device agent.

  5. 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

  6. System sees the device but Haptix doesn't — run xcrun devicectl list devices. If it appears there but not in haptix devices, restart the daemon: haptix stop && haptix start.

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 Mac-side screen capture to start 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. The screen-capture path and USB device control are macOS-side resources 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: Mac-side screen capture 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.

Screen capture stuck (no frame delivered)

Symptom: Screenshots fail with a timeout or "no frame available" error, but the device is connected and haptix status is healthy.

Fast path:

haptix capture restart

If that doesn't fix it, haptix capture status will tell you whether the issue is on the Mac (capture pipeline) or on the device (no connection). Worst case — Mac's screen-capture services need a full reboot. A coreMediaTimeout error message points at this when the simpler fixes haven't helped.

Bootstrap failed: 5: Input/output error on macOS Tahoe

Symptom: haptix start or haptix setup fails with Bootstrap failed: 5: Input/output error on macOS Tahoe.

Cause: Older daemon binaries weren't Developer ID signed with the hardened runtime + Camera entitlement, and Tahoe refuses to register them as a user agent.

Fix: Re-run the installer. The v1.5.2+ binary is properly signed.

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

The v1.5.2 installer was occasionally rejecting its own legitimately-signed binary as part of the codesign verification step; v1.5.3 resolves that. If you hit it, re-run the installer once more.

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.