Error codes
The set is closed: any failure without a code of its own is reported as INTERNAL.
ADB_NOT_FOUND,ADB_TIMEOUTandADB_FAILEDcome from every command that reaches adb.doctorreports them in its output instead.devicesreports them inerrorswhen the other platform could be listed.- On macOS, the
SIMCTL_*andDEVICECTL_*codes also come from the device listing that every command targeting a device runs.devicesreports them insideerrors.
NO_COMMAND
No command given. The message lists the commands.
From: all
UNKNOWN_COMMAND
The command name is not known.
From: all
INVALID_ARGS
Missing, extra, malformed or unknown arguments. An unknown key name, or one with no iOS key (BACK; on an iPhone also a key that types no character, such as DPAD_UP or F1). An app path that is not an existing .apk or .ipa file or .app directory, or an app for the other platform. A screenshot --out that does not end in .png. A malformed package name. A --since that is not Unix time in seconds, or a --lines outside 1 to 999999999. A --team that is not a 10-character team ID, or no --team when Xcode lists several teams and not exactly one paid.
From: all
ADB_TIMEOUT
adb did not answer in time: 10 s per call, 20 s for a ui-tree read, 10 s plus the duration for a long press or swipe, 30 s plus 1 s per started MB for install, 30 s for the start in launch. The message suggests adb kill-server. For ui-tree the cause is more often a stuck dump. For install it is more often an install prompt on the phone, which the message names first.
From: all that reach adb
ADB_FAILED
adb exited with an error. The message is adb's stderr, or Node's error when adb printed nothing. For launch, terminate and uninstall it can also be the error the device command printed. For logs, logcat's own error text or output that is not whole log records. A device that disconnects mid-command ends here.
From: all that reach adb
SIMCTL_NOT_FOUND
No simctl found: Xcode is missing or was never opened, or DEVELOPER_DIR points somewhere without one. See Requirements.
From: screenshot, install, launch, terminate, uninstall and logs on a simulator; device listing
SIMCTL_TIMEOUT
simctl did not answer in 30 s; for install, 30 s plus 1 s per started MB of the file (31 s for a .app). For logs, the read did not finish in 30 s; the message says what to pass to read less.
From: screenshot, install, launch, terminate, uninstall and logs on a simulator; device listing
SIMCTL_FAILED
simctl exited with an error, or printed something Karagöz does not expect. The message is simctl's stderr, or Node's error when simctl printed nothing; for unexpected output, unexpected simctl output: and its first line. For logs, log's own error, or output that is not log show's records.
From: screenshot, install, launch, terminate, uninstall and logs on a simulator; device listing
DEVICECTL_NOT_FOUND
No devicectl found: Xcode older than 15, or never opened, or only the Command Line Tools, or DEVELOPER_DIR points somewhere without one. See Requirements.
From: device listing
DEVICECTL_TIMEOUT
devicectl did not answer in 10 s; 30 s for a command on an iPhone, 120 s for installing the runner. For install on an iPhone, add 1 s for every started MB of the file. For launch on an iPhone the message names an app held by a debugger.
From: screenshot, ui-tree, install, launch, terminate, uninstall, logs --package, install-runner, uninstall-runner on an iPhone; device listing
DEVICECTL_FAILED
devicectl exited with an error, or printed something Karagöz does not expect. The message is devicectl's stderr, or Node's error when it printed nothing; for unexpected output, unexpected devicectl output: and its first line. For screenshot on an iPhone, any capture failure not listed under DEVICE_NOT_READY. For example, no connection to the phone, a developer disk image that could not be mounted, or a second capture of the same phone while one runs. For launch and terminate on an iPhone, devicectl's description and the phone's reason.
From: screenshot, ui-tree, install, launch, terminate, uninstall, logs --package, install-runner, uninstall-runner on an iPhone; device listing
NO_DEVICE
No device connected and none named. On macOS the message also names booting a simulator.
From: all but devices and doctor
DEVICE_NOT_FOUND
The named device is not connected.
From: all but devices and doctor
DEVICE_AMBIGUOUS
More than one device and none named, or a name that matches more than one.
From: all but devices and doctor
DEVICE_NOT_READY
The device is offline, unauthorized or similar, or the simulator is Booting or Shutting Down. For tap, swipe and key right after a boot: the simulator's input service did not answer within 4 s. For screenshot: an iPhone that is not paired yet, has Developer Mode off, is no longer paired with this Mac, or is locked since it restarted. For launch: a locked iPhone. For ui-tree, tap, swipe, text and key, also an iPhone not connected by USB cable, locked, or with a developer it does not trust yet. For those five, also a runner that did not start within 60 s (look at the phone: the passcode sheet for UI automation, or Enable UI Automation off). Or something else answering on the runner's port without this Mac's key, or another app holding that port. For logs: an iPhone not connected by USB cable, one this Mac holds no pairing record for, or one that refuses this Mac's session. The message says what to do.
From: all but devices and doctor
HELPER_FAILED
The iOS helper cannot run on this Mac: no Xcode selected, no swiftc (the Command Line Tools are not enough), a failed compile or a crash. Or an Xcode that changed a private interface Karagöz uses. For input on a simulator: no automation session, typing that failed, or no answer within 30 s. For the iPhone runner: no Apple account or team in Xcode, or a failed build (xcodebuild's error lines and the log path). Or xcodebuild failing to start the runner for a reason Karagöz does not know (the log path), or an iOS that changed a private interface the runner uses. For input on an iPhone: an event the runner could not play (its message), no answer within 30 s plus the gesture or typing time, or a runner that closed the connection. For logs on an iPhone: usbmuxd unreachable, a failed TLS handshake, or the phone's log service missing or refusing the archive. Or a stream that broke, ended early or sent nothing for 30 s. Or tar or log missing or failing (their own message), or log show not finished within 30 s. The message says which and what to do.
From: ui-tree, tap, swipe, text, key on a simulator or an iPhone; install-runner; logs on an iPhone
RUNNER_NOT_INSTALLED
A command on an iPhone found no Karagöz runner it can use. None is installed, or the installed one was built by another Karagöz or Xcode (or its build on this Mac was deleted). Or its profile does not include this iPhone or has expired. Or a runner from an older Karagöz is still answering (it signs nothing). The message names karagoz install-runner --device <UDID> and the MCP tool install_runner.
From: ui-tree, tap, swipe, text, key on an iPhone
NOT_SUPPORTED
For tap, swipe and key on an iOS simulator with Xcode 26 or older: 'tap' on iOS simulators needs Xcode 27 or later. For text with Xcode 27 or newer on a simulator older than iOS 27: 'text' on an iOS 26.2 simulator needs an iOS 27 or later simulator with Xcode 27 or later; .... For install-runner or uninstall-runner on another device: device <id> is not an iPhone; karagoz's runner runs only on iPhones. For screenshot on an iPhone with a devicectl older than Xcode 27's: 'screenshot' on an iPhone needs Xcode 27 or later: .... Argument checks come first.
From: tap, swipe, key on a simulator with Xcode 26 or older; text on a simulator older than iOS 27 with Xcode 27 or newer; screenshot on an iPhone before Xcode 27; install-runner and uninstall-runner elsewhere
CAPTURE_FAILED
The screen could not be read: bad screenshot data, missing display info, or a uiautomator failure. On iOS: a read the helper could not finish, or an app opened while the simulator's app accessibility was off (restart it). On an iPhone: a snapshot the runner could not take, no answer within 30 s, or a runner that closed the connection. For a tap or swipe on an iPhone in landscape: no panel size from devicectl. The message says which.
From: screenshot, ui-tree, tap --text/--id; tap, swipe on an iPhone
AUTOMATION_BUSY
Another UiAutomation client holds the device; on a simulator, a UI test holds automation mode.
From: ui-tree, tap --text/--id; text on a simulator
WRITE_FAILED
The screenshot file could not be written, or for logs on an iPhone, its temporary folder could not be created.
From: screenshot; logs on an iPhone
TEXT_UNSUPPORTED
The text has a character the target cannot type. On Android: anything but printable ASCII, newline, tab, ç, Ç and ß. On iOS: a control character other than newline and tab.
From: text
ELEMENT_NOT_FOUND
No node matches.
From: tap --text/--id
ELEMENT_AMBIGUOUS
More than one node matches.
From: tap --text/--id
ELEMENT_COVERED
The node's center is under the on-screen keyboard.
From: tap --text/--id
INPUT_BLOCKED
The device does not let adb inject input. On Xiaomi, Redmi and POCO, "USB debugging (Security settings)" is off; on vivo and iQOO, "USB simulated click".
From: tap, swipe, text, key
INSTALL_FAILED
The device refused the app. reason is Android's code, or simctl's <domain>:<code> on a simulator. On an iPhone, it is the <domain>:<code> of the deepest error devicectl reports. For install-runner, devicectl's message.
From: install, install-runner
UNINSTALL_FAILED
The device refused to remove the app, or it is an iOS system app (reason SYSTEM_APP). reason is Android's code, or simctl's <domain>:<code> on a simulator. On an iPhone, it is the <domain>:<code> of the deepest error devicectl reports. For uninstall-runner, devicectl's message.
From: uninstall, uninstall-runner
APP_NOT_FOUND
The package is not installed.
From: launch, terminate, uninstall, logs
APP_NOT_LAUNCHABLE
The package is installed but has no activity a launcher can start.
From: launch on Android
INTERNAL
A bug in Karagöz. Please report it with the message.
From: all