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 typederror.codeinstead 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
--verbosefor 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:
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 5if the element appears after navigation or an animation; - prefer
--id, or add--element-typeto 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
| Code | Fix |
|---|---|
notPaired | Pair the device in Xcode and confirm Trust on the device. |
developerModeDisabled | Enable Developer Mode in Settings on the device. |
deviceNotConnected | Connect the device by USB or reconnect it in Xcode. |
developerDiskImageUnavailable | Open the device in Xcode and wait for it to finish preparing. |
deviceLocked | Unlock the device. |
rotationLocked | Turn Orientation Lock off. |
rotationUnconfirmed, displayOrientationMismatch | The display lagged behind the interface, or the app does not support the orientation. No input was sent; rotate again, then read the screen. |
deviceStreamReplaced | Xcode Device Hub's screen view took the native stream. Close it, or use the screenshot stream formats. |
treeUnavailable | The accessibility tree was too large to read in 20 seconds. Navigate to a smaller screen. |
unsupportedOnDevice | The 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-videowrites binary frames to stdout. Redirect or pipe it. - Unfinished MP4: stop recordings with
Ctrl+Corkill -INT <pid>. SIGKILL skips finishing the file. stream-videorefuses--output json: its stdout carries frames, so it has no JSON result.
Batch
- A step with its own
--udidis rejected; put--udidonaxe batch. - For flows that change screens, set
--wait-timeoutor--ax-cache perStep. screenshot,describe-ui, video,slideranddragare not plain batch steps; run them on their own.