Haptix/Docs

Troubleshooting

Common issues and how to fix them.

Recovery model

The daemon self-heals. Screen capture recovers on its own from interruptions, and the device link auto-recovers — there's no manual repair step. If something seems stuck:

haptix health                # liveness/status rollup; exit 0 means healthy
haptix watch                 # live glanceable status, refreshes ~2s until ctrl-c
haptix stop && haptix start  # restart the daemon if it's wedged

The entries below cover the most common cases.

Camera permission required

Symptom: start_session returns cameraPermissionDenied or cameraPermissionRestricted.

Cause: 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 setup                 # walks through requesting or re-enabling Camera

You can also enable it manually in System Settings → Privacy & Security → Camera. Enable Haptix in the list, then restart the daemon:

haptix stop && haptix start

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

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.

Two phones with the same name

Symptom: Two iPhones or iPads are connected to the same Mac and Haptix can't tell them apart.

Fix: On one of the devices, set a different name in Settings → General → About → Name, then reconnect it. Once the two devices have distinct names, Haptix can bind to the right one.

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.

Tap on a control behind the keyboard is refused

Symptom: A tap on a control fails and Haptix reports the target is hidden behind the on-screen keyboard.

Cause: When the keyboard is up, the agent refuses to interact with controls it covers rather than silently missing them.

Fix: Dismiss the keyboard first (drag from the content area down past the screen bottom), then retry the tap. You can check whether the keyboard is up and which region it covers:

haptix tool keyboard-state

The same information is available over MCP via the keyboard_state tool.

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.

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

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.

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

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.

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.