# Error codes The set is closed: any failure without a code of its own is reported as INTERNAL. **Branch on error.code, not the message.** Messages are for people and can change. - `ADB_NOT_FOUND`, `ADB_TIMEOUT` and `ADB_FAILED` come from every command that reaches adb. `doctor` reports them in its output instead. `devices` reports them in `errors` when the other platform could be listed. - On macOS, the `SIMCTL_*` and `DEVICECTL_*` codes also come from the [device listing](https://karagozmcp.com/docs/device-selection/#on-macos) that every command targeting a device runs. `devices` reports them inside `errors`. ## Codes ### 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_NOT_FOUND No `adb` found. See [Requirements](https://karagozmcp.com/docs/requirements/#adb). From: all that reach adb ### 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](https://karagozmcp.com/docs/requirements/#ios-simulator-macos). 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](https://karagozmcp.com/docs/requirements/#iphone-macos). 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 ` 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 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 `:` on a simulator. On an iPhone, it is the `:` 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 `:` on a simulator. On an iPhone, it is the `:` 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