AXedocs
Install

Troubleshooting

Common AXe failures, what their error codes mean, and the fastest fix for each.

Quick triage#

  • Run axe doctor --udid <UDID>. It checks that a simulator is booted, or that a device is paired, in Developer Mode, connected, unlocked and ready for screenshots.
  • Use axe --output json <command> to get the typed error.code instead of reading the message.
  • For a selector failure, run axe describe-ui --udid <UDID> and check that the current screen has the id, label or value you used.
  • Add --verbose for the full receipt. It never changes the exit status or the error code.

targetNotFound#

No simulator or device has the UDID. AXe looks among simulators first, then among the devices Xcode knows. Check axe list-simulators and axe list-devices. Simulator names and booted are not accepted; pass the UDID.

notBooted#

Boot the simulator:

shell
xcrun simctl boot <UDID>

Right after boot, give the simulator a few seconds before the first accessibility read. On the iPhone Duo, wait until axe displays succeeds; it reports displayUnavailable for about 12 seconds after boot.

Accessibility channel disconnected#

The simulator's accessibility service can occasionally disconnect while the simulator itself stays booted. For the channel-disconnect and DTX errno 24 failures, AXe makes one bounded recovery attempt: it restarts the simulator's test manager service, reads the UI again and retries the command once. If that retry also fails, AXe returns the error instead of looping.

elementNotFound or ambiguousElement#

The selector matched nothing, or several elements. Read the current screen, then:

  • add --wait-timeout 5 if the element appears after navigation or an animation;
  • prefer --id, or add --element-type to narrow duplicate labels;
  • for a list, use gesture scroll-up --until-label "<label>" to scroll it into view first.

If a matched row contains a switch, the default automatic tap style taps the switch. Use --tap-style simulator if you meant the row.

busy#

Another AXe command holds the simulator or device. Wait for it to finish; for example, a record-video in another terminal holds a capture lease during each frame.

cleanupUncertain or quarantined#

AXe could not confirm that a touch or key was released, so it blocks further input on that target. Check the device, then delete the quarantine record file named in the error. AXe never replays the input.

invalidArguments from type#

type uses the US keyboard layout. A character it cannot send, such as é or £, fails before anything is typed. In a simulator, stage such text with axe clipboard copy --stdin and paste it in the app.

Gestures land in the wrong place#

Coordinates are logical points in the current orientation, not screenshot pixels. Divide pixel positions by the screen scale that axe displays reports. A gesture preset step in a batch on a simulator other than the iPhone Duo assumes 390×844 unless you pass --screen-width and --screen-height.

inputUnavailable#

The simulator has no DTUHID touch service, which coordinate gestures such as pinch and rotate need. Use a current Xcode and simulator runtime.

DTUHID guest barrier timed out#

This affected commands sent straight after button home on Xcode 27.2 in earlier releases and is fixed in AXe 2. Upgrade with brew upgrade axe.

Physical device problems#

CodeFix
notPairedPair the device in Xcode and confirm Trust on the device.
developerModeDisabledEnable Developer Mode in Settings on the device.
deviceNotConnectedConnect the device by USB or reconnect it in Xcode.
developerDiskImageUnavailableOpen the device in Xcode and wait for it to finish preparing.
deviceLockedUnlock the device.
rotationLockedTurn Orientation Lock off.
rotationUnconfirmed, displayOrientationMismatchThe display lagged behind the interface, or the app does not support the orientation. No input was sent; rotate again, then read the screen.
deviceStreamReplacedXcode Device Hub's screen view took the native stream. Close it, or use the screenshot stream formats.
treeUnavailableThe accessibility tree was too large to read in 20 seconds. Navigate to a smaller screen.
unsupportedOnDeviceThe command is simulator-only. See what works on a device.

If a modal alert blocks the accessibility tree, close it on the device and read again.

Settings#

settingUnsupported means the device, OS or Xcode lacks the setting: axe settings needs Xcode 27, status bar overrides are simulator-only, and iOS 27.2 offers one Liquid Glass style. After turning VoiceOver on and off, tap OK on the "VoiceOver Gestures" alert; it blocks input until you do.

Agent mode refusals#

A refusal sent no input and usually returns the current screen. Act from that capture; sending the identical command again gets the same answer. See Agent Mode refusals.

Video#

  • Garbled terminal: stream-video writes binary frames to stdout. Redirect or pipe it.
  • Unfinished MP4: stop recordings with Ctrl+C or kill -INT <pid>. SIGKILL skips finishing the file.
  • stream-video refuses --output json: its stdout carries frames, so it has no JSON result.

Batch#

  • A step with its own --udid is rejected; put --udid on axe batch.
  • For flows that change screens, set --wait-timeout or --ax-cache perStep.
  • screenshot, describe-ui, video, slider and drag are not plain batch steps; run them on their own.