Docs Operation reference Error codes
Error codes#
Every error code tomaccoctl returns, 483 codes, generated from assets/errors.json. A failure is {"ok":false,"error":{"code":...,"message":...,"remedy":...}}, and over MCP the same object under structuredContent.error. Branch on code. The message says what happened this time; when the place that failed has no remedy of its own, remedy is the general one below. In the middle column, … stands for a value the message fills in. All operations.
| Code | What it means | What to do |
|---|---|---|
action_unsupported | project.dependency_updates reads Gradle builds, pubspec.yaml, package.json dependencies and Package.resolved; this project has none. | Use an explicitly configured project task for framework-specific commands. |
adb_forward | ADB did not allocate a forwarding port. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
ambiguous_selector | Selector matched … elements; refine it or specify index. | Add properties to the selector, or pass index. |
analyzer_failed | No analyser produced a result; see report.json. | Read the message and the job's log (job.logs); fix the cause and try again. |
analyzer_output | dart analyze printed no JSON. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
android_project_missing | No Gradle project in …/android. | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
app_action_failed | Device action failed. | Read the message and the job's log (job.logs); fix the cause and try again. |
app_container_unavailable | The iPhone did not open the container of … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
app_crashed | … … during the scenario. | Read the crash with testing.crashes or device.logs, fix it and run again. |
app_not_built | Expected one xtool/*.app in …, found … | Run project.execute with platform ios for an xtool project, and wait for its job. |
app_not_debuggable | Android refused run-as for this app; install a debuggable build for the current primary user. | Install a debuggable build of the app, such as a debug build from project.run. |
app_not_installed | … is not installed. | Install the app with device.install or project.run. |
app_not_running | … is not running. | Launch the app first, for example with device.app. |
apple_companion_failed | A display session with a device did not start or stopped answering. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
apple_companion_timeout | The Mac simulator did not become ready within 75 seconds. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
apple_runtime | A display session with a device did not start or stopped answering. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
application_id_ambiguous | Several installed apps match … | Pass the exact bundle_id from ios.apps. |
application_id_required | The request was refused; the message says why. | Pass bundle_id with the app's bundle identifier. |
application_id_unknown | The build files do not state this app's application ID. | Pass bundle_id with the app's application ID. |
approval_denied | The desktop asked the person about a destructive agent call and they denied it, pressed Escape, or the request timed out. | Ask the person, or have them approve it in the Tomacco window; desktop approval is set with settings.configure approval. |
artifact_missing | Screenshot command produced no artifact. | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
audio_stopping | The previous audio stream is still stopping; retry shortly. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
audio_unsupported | Output forwarding is currently available for Android 11 and newer. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
authentication_failed | Google did not return an access token. | Check that the service-account key is valid and has access in Play Console. |
avd_exists | An emulator with that name exists. | Choose another name, or use the existing one with android.avd_start. |
avd_in_use | Stop the emulator before changing its hardware settings. | Unrecognized emulator lock files are preserved. |
avd_not_found | Unknown AVD: … | Use android.avds or android.avd_create. |
baseline_conflict | Two devices would write different screenshots to the same baseline file. | Approve the screens one device at a time, or give each device its own baselines folder. |
baseline_missing | No baseline at … | Create the baseline with update_baseline:true after checking the image is right. |
baseline_plugin_missing | No module of the build applies the androidx.baselineprofile Gradle plugin. | Apply the plugin to the app module and add the producer module it names, or create the app with project.create kind compose and performance:true. |
baseline_profile_exists | src/main/baseline-prof.txt (or the destination) already holds a different profile. | Pass overwrite:true to replace it; the old file is kept beside it as .bak. |
baseline_profile_missing | The project or module has no baseline profile file, or the file holds no rules. | Generate one with profile.baseline_profile, or write src/main/baseline-prof.txt. |
baselines_missing | record_baselines ran screen steps whose baselines did not exist yet; it saved the screens instead of comparing them. | Review them with testing.baselines review and approve them, then run the scenario again. |
benchmark_module_ambiguous | The build has several Macrobenchmark or app modules, and none was named. | Pass module, a Gradle path from project.inspect performance. |
benchmark_module_missing | The build has no Macrobenchmark module, or no module with the name given. | Add a com.android.test module that depends on androidx.benchmark:benchmark-macro-junit4, or create the app with project.create kind compose and performance:true. |
benchmark_results_missing | No benchmarkData.json from a Macrobenchmark run was found under the project. | Run profile.macrobenchmark first, then read its results with job_id. |
binary_file | This file is not UTF-8 text. | files.read and files.write handle UTF-8 text only. |
budget_exceeded | Outside the performance budget: … | Compare the report with its baseline (profile.compare) to find the regression, or raise the budget if it was intended. |
builtin_profile | The request was refused; the message says why. | Choose a new ID; built-in profiles cannot be replaced. |
bundle_id_mismatch | The built app is …, not … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
bundletool_failed | bundletool reported no sizes. | Read the message and the job's log (job.logs); fix the cause and try again. |
capture_failed | Evidence capture failed. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
capture_incomplete | Device screenshot has not completed successfully. | Inspect job.get and job.logs. |
capture_not_running | android.network_capture stop or summary was called with no capture running on that device. | Start one with android.network_capture start and opt_in true. |
capture_running | A network capture is already running on that device. | Stop it with android.network_capture stop before starting another. |
capture_timeout | ADB screenshot timed out. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
catalogue_full | At most 1000 custom profiles are supported. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
checksum_mismatch | The download from … does not match its published checksum and was deleted. | Try again; if it repeats, the download source changed and the pinned checksum needs an update in a new Tomacco version. |
compile_failed | cmd package compile did not answer Success for the app. | Read the message; the app must be installed and its package manager must accept the compiler filter. |
config_unsupported | The request was refused; the message says why. | Update the bundle identifier in this project's xtool configuration manually. |
conflicting_display_profile | This device model has its own display; omit display_profile. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
conflicting_storage | The virtual iOS device or its research engine refused the request or stopped answering. | Select one access mode per virtual disk. |
consent_declined | The person said no, or closed the question, when the MCP client asked them before this step. | Do not repeat the call unless the person changes their mind; ask them what to do instead. |
console_log_limit | Guest console exceeded 8 MiB. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
coverage_not_configured | coverage was asked for, but the module's build files enable no coverage report (no enableUnitTestCoverage, jacoco or Kover). | Add the line the error names to the module's build file, then run again. |
crash_report_unreadable | The request was refused; the message says why. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
database_busy | The job database stayed locked by another Tomacco process. | Try again in a moment; if it stays busy, check for a stuck tomaccoctl process. |
database_error | The job database could not be opened or read. | Check that TOMACCO_HOME is writable and its disk is not full; tomaccoctl report bundles the details. |
debug_adapter_error | The debugger could not start, attach or answer. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
debug_disconnected | Debug adapter closed stdout. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
debug_forward | ADB did not allocate a local native-debug port. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
debug_overflow | Too many unprocessed debug events. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
debug_protocol | DAP header too large. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
debug_session_unavailable | The debugger could not start, attach or answer. | Start a new debug session or inspect debug.list. |
debug_timeout | Adapter did not initialize the target. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
debug_worker_failed | Debug worker exited; inspect … | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
dependencies_missing | … is not installed in …/node_modules. | Run … in …, then call project.run again. |
desktop_missing | Tomacco desktop is not installed. | Build with CMake and run python3 install.py. |
desktop_stale | The running Tomacco desktop (…) is not the installed version … and cannot be asked to quit. | Close that window, then open Tomacco again. |
desktop_start_failed | Desktop exited during startup. | Read … |
desktop_start_timeout | Desktop has not opened its control socket. | Read … |
desktop_unsaved | The running Tomacco desktop (…) is not the installed version …, and it has unsaved files. | Save or discard them in that window and close it, then open Tomacco again. |
device_busy | This iPhone already has an active native session. | Wait for the job or session using it to end (job.list), or stop it if the person agrees, then try again. |
device_debug_busy | An existing debugger owns this Android device; use or disconnect that session first. | Wait for the job or session using it to end (job.list), or stop it if the person agrees, then try again. |
device_failed | Failed on … | Read the message and the job's log (job.logs); fix the cause and try again. |
device_required | Several iPhones are connected; pass device. | Pass device with an ID from device.list. |
display_unavailable | The device did not report its density. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
display_unknown | … reported no screen size and density. | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
download_failed | Downloading … failed (curl exit …): … | Check the network connection and try again; retry where the operation offers it. |
duplicate_component | Research seal overrides must be unique. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
duplicate_profile | Import contains duplicate IDs. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
element_disabled | Selected element is disabled. | Wait until the element is enabled, or check the app's state before acting. |
element_input_failed | A step Tomacco ran did not succeed. | Read the message and the job's log (job.logs); fix the cause and try again. |
element_timeout | Element did not become … within …s. | Check with testing.find or a screenshot what the screen shows; raise the timeout if the app is only slow. |
emulator_no_display | An emulator with a window needs X11 (DISPLAY, or XWayland on Wayland), and this session has none. | Start it with headless true, or run it from a desktop session with XWayland. |
emulator_refused | The emulator refused …: … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
engine_changed | PMP engine changed after submission. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
engine_exited | PMP engine exited before QMP. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
engine_log_limit | PMP engine exceeded the 8 MiB log budget. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
engine_shutdown_failed | Engine exited with … | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
engine_shutdown_timeout | Engine did not finish flushing its working image. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
engine_timeout | PMP engine did not open QMP. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
file_conflict | The file changed after files.read gave its digest. | Read it again with files.read, merge the changes, and write with the new digest as if_match. |
file_exists | Export destination already exists: … | Choose another destination, or remove the existing file if the person agrees. |
file_too_large | Text editing is limited to files up to 1 MiB. | Edit the file with another tool; files.read and files.write handle text up to 1 MiB. |
firmware_incomplete | The virtual iOS device or its research engine refused the request or stopped answering. | Extract the required boot components first. |
firmware_modified | PMP bundle changed after submission. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
flutter_ios_missing | This is not a Flutter project with an ios directory. | Run flutter create --platforms ios . in the project. |
flutter_setup_required | This Flutter install still has Apple's macOS gen_snapshot. | Call ios.flutter_setup once per Flutter version. |
form_factor_unsupported | The system image is for TV, Wear, Automotive, XR or Desktop, which Tomacco does not create AVDs for. | Create it with avdmanager and the SDK device definition the error names, or use a phone or tablet image. |
frame_missing | The debugger could not start, attach or answer. | Read the stack before reading frame variables. |
git_failed | git could not list the changed files for testing.impact. | Run it in a Git working tree, or pass the changed files explicitly. |
guest_diagnostic_failed | The virtual iOS device or its research engine refused the request or stopped answering. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
guest_observation_timeout | The guest did not complete both platform observations. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
guest_script_failed | Guest script exited with … | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
guest_shell_timeout | No verified command response from the restore shell within the requested time. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
heap_dump_failed | The heap dump pulled from the device is empty. | Heap dumps need a debuggable app, or an emulator image without Google Play. |
incomplete_research_inputs | Research graft preparation requires kernel, boot_manifest and device_tree together. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
input_too_large | JSON exceeds 2 MiB: … | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
install_refused | The installer refused a change: a path outside the home, a symbolic link, a command it did not install, a file changed since installation, or a damaged backup. | Read the message, move or restore the file it names, then run the installer again. |
instrumentation_protocol | Invalid Android response. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
instrumentation_required | Unicode input requires Tomacco's Android instrumentation. | Run testing.setup for this device, wait for success, then retry. |
instrumentation_unavailable | Android UI automation is not ready. | Run testing.setup for the selected device, wait for success, then retry. |
integration_test_missing | This Flutter project has no integration_test directory. | Add the integration_test package as a dev dependency and its tests in integration_test/, as Flutter's integration testing guide describes. |
invalid_application | … is not among the apps a start stages: {RESEARCH_APPLICATION} and the listed bundles. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_application_bundle | This bundle uses the owned diagnostic app's bundle identifier; choose another. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_argument | The arguments do not match the operation's schema: an unknown key, a wrong type, or a value out of range. Nothing ran. | Correct the argument the message names; tomaccoctl schema OPERATION lists the accepted keys, types and limits. The call is safe to repeat. |
invalid_artifact | Not a readable ZIP-based Android package. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_baseline | The coverage baseline is neither a saved testing.coverage report nor JaCoCo XML. | Pass a report saved by testing.coverage or a JaCoCo XML file. |
invalid_boot_display | Boot display dimensions must be 64..4096. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_bounds | Selected node has no usable bounds. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_capture | Live frame sequence is exhausted. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_capture_path | Capture directory was replaced. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_command | Missing command. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_control_action | Unsupported input action. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_control_socket | Missing control directory. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_controller_snapshot | Expected bounded controller JSON. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_coordinates | … must be between 0 and 1. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_credentials | An argument, file or response is not in the form Tomacco accepts. | Pass the path of a Google service-account key JSON with access to the app. |
invalid_debug_session | seconds must be 10 to 86400. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_debug_target | target must be a PID or a process name: 1 to 64 ASCII letters, digits, '.', '_' or '-'. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_device_model | This is not a device model the virtual iOS device can be described as. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_display_profile | An argument, file or response is not in the form Tomacco accepts. | Use WIDTHxHEIGHT@HZ:WIDTH_MMxHEIGHT_MM; pixels 64..8192, Hz 1..120, mm 10..2000, with matching pixel and physical aspect ratios. |
invalid_duration | Pointer duration must be 1–2000 ms. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_endpoint | Unsupported store endpoint. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_engine | Engine is not executable. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_engine_option | bti must be keep or off. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_export | The path is not a screen.export bundle, or its screen.json cannot be read. | Give the directory screen.export wrote, or its screen.json. |
invalid_firmware | Research components are missing. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_glob | An argument, file or response is not in the form Tomacco accepts. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_guest_network | guest_network must be off or nat. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_guest_receipt | The guest operation receipt is incomplete or malformed. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_guest_request | bundle_id must be an application identifier supplied with install. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_guest_response | Guest response exceeds the protocol limit. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_guest_status | The guest did not report its current worker state. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_guest_tools_request | A previous trust cache requires the corresponding previous tools. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_hierarchy | The hierarchy is larger than 16 MiB. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_hold | Home hold must be 1–1000 ms. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_host_cpu_policy | host_cpu_policy must be scheduler or performance. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_input | Unknown Flutter command. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_interactive_guest | An argument, file or response is not in the form Tomacco accepts. | Select an iOS job started with interactive=true. |
invalid_ios_application | An argument, file or response is not in the form Tomacco accepts. | Name an .ipa archive or an .app directory. |
invalid_job | Invalid artifact signature. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_json | …: … | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_key | … has no key on the virtual iPhone; use a QEMU key name or home. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_keys | An argument, file or response is not in the form Tomacco accepts. | Supply one to eight QEMU key names. |
invalid_memory_range | An argument, file or response is not in the form Tomacco accepts. | Use a hexadecimal physical address. |
invalid_metadata | An argument, file or response is not in the form Tomacco accepts. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_native_binary | An argument, file or response is not in the form Tomacco accepts. | Select an unstripped Android ELF library or executable. |
invalid_path | The pulled files are written as one .tar archive; name the output FILE.tar. | Name the file itself, or remove the link. |
invalid_pattern | An argument, file or response is not in the form Tomacco accepts. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_pcc_boot | PCC configuration requires a normal sealed-system boot with a root disk. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_platform_observations | Non-UTF-8 platform data. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_pmp_breakpoint | An argument, file or response is not in the form Tomacco accepts. | Use an aligned ARM64 instruction address in hexadecimal. |
invalid_pmp_bundle | An argument, file or response is not in the form Tomacco accepts. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_pmp_cpu_identity | Invalid …: use a hexadecimal value within mask 0x… | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_profile | Custom catalogue must be an array. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_project | An argument, file or response is not in the form Tomacco accepts. | Select an .xcodeproj or .xcworkspace. |
invalid_qmp | Translation statistics must be a text report. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_reference | Invalid object reference. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_report | … has no metrics. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_report_path | Control request is outside the owned guest directory. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_request | Unknown option: … | Run tomaccoctl --help for the commands. |
invalid_response | go-ios returned no application array. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_restore_bridge | Bridge receipt is too large. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_schema | An argument, file or response is not in the form Tomacco accepts. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_screenshot | Device returned an invalid or oversized PNG. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_secret | An argument, file or response is not in the form Tomacco accepts. | Name a small .p8 private key file. |
invalid_selector | An argument, file or response is not in the form Tomacco accepts. | Specify at least one semantic property. |
invalid_session | Preview runtime directory is not owned by the current user. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_session_log | Line … is not JSON: … | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_settings | remotes.json must be an object. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_step | Unknown scenario action. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_task | Each task must be a non-empty command array. | Define tasks in tomacco.json. |
invalid_tcg_profile | tcg_profile must be true or false. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_temporary_directory | Temporary directories must be private. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_text | An argument, file or response is not in the form Tomacco accepts. | Supply 1 to 1024 characters of text. |
invalid_text_layout | No key table for the layout …; name layout us or de. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_tool | Unknown tool: … | Name one of the tools doctor lists. |
invalid_toolchain | clang must name an executable file (a clang 22 release). | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_translation_cache | translation_cache_mib must be an integer between 1 and 4096; requests above 2048 require a range-independent engine chain capability. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_trust_cache | path must name a trust-cache module file. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_url | An argument, file or response is not in the form Tomacco accepts. | Use a complete deep link with a scheme. |
invalid_usb_guest | An argument, file or response is not in the form Tomacco accepts. | Select a paravirtual iOS job started with usb=true. |
invalid_variant | The build files have no variant … | Use one of: … |
invalid_working_image | Working image must be a separate owner-only regular copy, with one link and the same page-aligned size as the source ramdisk. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_workspaces | Saved workspaces are malformed; restore workspaces.json from a backup. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
invalid_xcode_project | … is not an .xcodeproj directory. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
ios_boot_failed | The virtual iOS device or its research engine refused the request or stopped answering. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_control_busy | Another control action is in progress for this guest. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_control_ended | The emulator is no longer running; the job is finishing. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_control_starting | The guest has not published its control monitor yet. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_emulator_busy | An iOS emulator job is already active. | Reuse its job or cancel it before starting a different guest. |
ios_frame_file_unavailable | No private runtime directory is available for live frames. | Use the default inline frame transport. |
ios_guest_busy | A native framework request is still in progress; the emulator was not stopped. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_control_unavailable | The virtual iOS device or its research engine refused the request or stopped answering. | Select an iOS job with guest_control_backend enabled. |
ios_guest_crash_reports_failed | The guest could not read its crash reports. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_disconnected | The guest control stream closed while sending. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_not_idle | The native worker has not confirmed it is idle; the emulator was not stopped. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_paused | The virtual iOS CPU is not running. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_receipt_unavailable | The guest could not read its operation receipt. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_starting | The guest control transport has not started. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_stopped | The virtual iOS job has stopped. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_guest_timeout | The native guest did not reply before the request deadline. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_home_unavailable | The virtual iOS device or its research engine refused the request or stopped answering. | Start with input_transport=usb-hid for the iOS Home usage. |
ios_input_timeout | Pointer sequence exceeded its deadline. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_power_button_unavailable | The timed side button requires the tomacco-vphone machine. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_prepare_busy | This guest-tools output has an active job. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_restore_busy | This virtual guest already has an active restore. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_setup_confirm | An ios.virtual.setup stage marked ask_first was run without confirm. | Tell the person what the stage costs (why_ask under details.stage) and call again with confirm:true once they agree. |
ios_setup_inputs_invalid | Some of the person's own inputs are not the ones the chain needs. | Read each failed entry's problem under details.inputs and fix it; nothing long has started. |
ios_setup_manual | … is run by hand. | Run the stage's commands by hand as its manual entry says, then call plan again. |
ios_setup_needs_checkout | The engine is built in a Tomacco source checkout's .tooling. | Run tomaccoctl from a source checkout (git clone the project, then use its tomaccoctl). |
ios_setup_needs_input | … needs: … | Check that pcc_firmware is the unpacked PCC 23E5207q image, move work/boot aside and run the boot stage again. |
ios_setup_out_of_order | The … stage is not done yet (…); the chain runs in order. | Run the stage the message names first; ios.virtual.setup step plan lists the order. |
ios_setup_partial | The virtual iOS device or its research engine refused the request or stopped answering. | Move the half-finished output aside (nothing is deleted for you), then run the stage again. |
ios_touch_has_no_hover | The virtual iOS device or its research engine refused the request or stopped answering. | Use click or drag for a touchscreen contact. |
ios_touch_lane_required | touch_down needs a persistent client; a one-shot call would end with the contact down. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_touch_not_down | No contact is held down for this guest. | Press again with touch_down. |
ios_usb_bridge_busy | This virtual guest already has a USB bridge job. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_application_conflict | Another listed bundle already uses the bundle identifier … | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_application_unknown | No listed app bundle has this path or bundle identifier. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_busy | A start or stop is in progress; try again when it has ended. | Wait for the start or stop to end (ios.virtual.status), then try again. |
ios_virtual_disk_space | The start copies … of disks into …, but that filesystem has … free… | Free disk space on that filesystem, or clean up with ios.virtual.cleanup and storage.prune. |
ios_virtual_guest_state_unknown | The virtual iOS device job could not be observed; its state is unknown. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_host_too_small | The virtual iPhone needs an x86_64 host with at least 12 GiB of memory. | Use a larger x86_64 machine; Android emulators still work here. |
ios_virtual_locked | The virtual iOS device or its research engine refused the request or stopped answering. | Unlock the phone in its window (Home, or a swipe up on a model without one), then try again. |
ios_virtual_log_unavailable | The guest job has no console log yet. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_no_verified_run | The phone has no verified run to save; stop a run with ios.virtual.stop first. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_not_running | The phone is not running; start it with ios.virtual.start. | Start it with ios.virtual.start and follow the job until the phone is up. |
ios_virtual_profile_invalid | The virtual iOS device guest job must be a job ID or null. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
ios_virtual_running | The phone is running or its last run has not been stopped; stop it first. | Stop it with ios.virtual.stop first. |
ios_virtual_state_exists | A saved state is already called … | Choose another name, or pass replace:true to point it at the current verified run. |
ios_virtual_state_missing | The disks of the saved state … are gone. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_state_unknown | No saved state is called … | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_state_unsaved | The current verified run is not saved; a later start may delete its disks. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
ios_virtual_unconfigured | No virtual iOS device profile is configured. | Set the virtual iOS device up as doctor's next_steps say, or with ios.virtual.setup. |
iphone_runtime | A display session with a device did not start or stopped answering. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
jdwp_error | JDWP …/… returned error … | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
job_cancelled | A job followed with --wait was cancelled. | Start it again if the cancellation was not intended; job.events shows who cancelled it and when. |
job_failed | A job followed with --wait ended failed. | Read the job's log with job.logs, fix the cause and start it again. |
job_not_found | No job has that ID in this data directory. | List recent jobs with job.list; jobs live under TOMACCO_HOME, so a different TOMACCO_HOME has other jobs. |
job_timed_out | A job followed with --wait ran out of its timeout. | Read job.logs for where it stopped; start it again with a longer timeout argument if it was only slow. |
launch_failed | am start answered Status: … | Read the message and the job's log (job.logs); fix the cause and try again. |
launch_unmeasured | am start -W reported no TotalTime for this launch. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
launcher_missing | Application has no launcher activity. | Install the app or pass an explicit activity to device.app. |
lldb_server_arch | NDK lldb-server architecture does not match the target. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
lldb_server_missing | The configured NDK has no … lldb-server. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
macos_required | project.execute builds Flutter iOS apps only on macOS. | On Linux call ios.flutter_build (it needs ios.toolkit_install), or use remote.run with an SSH Mac workspace. |
managed_device_not_found | The Gradle managed device or group is not declared in the build files. | Use a name from the managedDevices block, or all. |
mark_not_found | The last screen.marks of this device has no mark with that number. | Use a number from the marks in the last screen.marks result, or call screen.marks again. |
mark_stale | The screen no longer matches what the mark was made from, so nothing was tapped. | The screen changed since screen.marks; call it again and tap the new number. |
marks_missing | screen.tap was given a mark but no screen.marks or screen.tree has been made for this device. | Call screen.marks for the device, look at the result, then tap a number from it. |
mdns_unavailable | adb cannot discover devices on the network: … | Update the Android platform tools, or pair with the code through android.connect. |
meminfo_unreadable | dumpsys meminfo named no process of the app. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
metro_unreachable | Metro does not answer on port …: … | Wait until the job's log says Metro is serving, or run the app again with project.run. |
module_not_found | No Android application module found. | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
native_arch_mismatch | The unstripped binary and Android process have different architectures. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
native_debug_identity | run-as did not return an application UID. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
native_debug_server_failed | NDK lldb-server exited; inspect native-server.log. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
native_debug_setup | Device debugger transfer failed; inspect native-transfer.log. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
native_debug_timeout | Timed out transferring the NDK debugger. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
native_process_executable | Expected an Android app process executable. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
native_process_mismatch | The selected PID does not belong to the requested application. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
native_process_missing | The debugger could not start, attach or answer. | Select the PID of a running app process, or enable launch for a debuggable build. |
ndk_missing | Something the request names does not exist or is not set up. | Install an NDK with android.sdk_install and set settings.configure android_ndk. |
no_coverage_reports | No JaCoCo or Kover XML report was found where Gradle writes them. | Run the tests with coverage first (project.execute coverage true), or pass the report path. |
no_devices | No Android device is connected. | Start an emulator with android.avd_start or connect a phone, then check device.list. |
no_live_device | tomaccoctl omarchy screenshot found no connected device to capture. | Connect a device or start an emulator with runtime.start or the panel, then try again. |
no_test_results | The request was refused; the message says why. | Run the tests first: project.execute with action test or instrumented-test, or testing.run. |
not_a_run_directory | The directory is not a testing.run output directory. | Pass the directory a testing.run job wrote (its report.json is there). |
not_android_project | No Android Gradle build in this project. | Pass the project root that holds settings.gradle(.kts), or its android/ directory. |
not_directory | Something the request names does not exist or is not set up. | Pass a directory. |
not_emulator | This operation requires an emulator serial. | Pass an emulator serial from device.list, such as emulator-5554. |
not_executable | Not executable: … | Point settings.configure executables at an executable file, or chmod +x it. |
not_file | Something the request names does not exist or is not set up. | Pass a regular file. |
not_foldable | A posture was set on an emulator whose AVD has no hinge. | Use a foldable profile (one with openWidth) in android.avd_create or android.avd_profile. |
not_interactive | This job has no interactive session. | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
not_ios_emulator_job | The virtual iOS device or its research engine refused the request or stopped answering. | Select an iOS emulator job. |
not_stoppable | This job has no running step that stop ends early. | job.cancel ends any job, without keeping its result. |
nothing_to_analyze | No analyser applies: the project has no pubspec.yaml, and no eslint or tsc (with tsconfig.json) in node_modules/.bin. | Install eslint or typescript as a dev dependency, or open a Dart or Flutter project. |
nothing_to_check | No versioned dependency or plugin in the versions catalog or build files. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
notification_not_snoozed | Android did not snooze … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
ocr_action_unsupported | A field cannot be filled by text read off the screen. | Tap the field with a click, then type with a text step or ios.emulator.control. |
ocr_failed | tesseract could not read the screenshot. | Read the message and details.stderr; check that the image is a valid PNG, and try again or read a smaller region. |
ocr_language_missing | tesseract has no data for the language asked for. | Install the language's data (tesseract --list-langs lists what is installed) or use language eng. |
ocr_unavailable | Reading text off a screenshot needs tesseract, and it is not installed. | Install tesseract and its English data (Arch: pacman -S tesseract tesseract-data-eng; Debian and Ubuntu: apt install tesseract-ocr), or set TOMACCO_TESSERACT to the executable; capabilities.ocr says whether it is found. |
off_screen | (…, …) lies outside the …x… screen. | Use coordinates inside the screen size the message gives. |
offline | The Maven repositories cannot be reached: … did not resolve. | Connect to the network, or try again later. |
omarchy_repair_unavailable | tomaccoctl omarchy repair needs the panel's sources, which the installation keeps beside the program, and found none: this installation is from before they were kept. | Run the installer of a release package with --omarchy once; later repairs need no package. |
operation_not_found | Unknown operation: … | Use the operation the remedy suggests; tomaccoctl schema --names lists every operation. |
opt_in_required | A network capture records traffic, so it starts only when asked for explicitly. | Pass opt_in true to android.network_capture start. |
output_exists | The request was refused; the message says why. | Choose a new output path, or move the old one aside. |
outside_project | The request was refused; the message says why. | Use a path inside the project, relative to its root. |
package_missing | No Package.swift found in … | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
page_load_failed | The web layout preview did not load or answer. | Check that the dev server answers at the URL, then preview.reload or start the preview again. |
page_timeout | Page did not become ready. | Check that the dev server answers at the URL, then preview.reload or start the preview again. |
pairing_failed | adb could not pair: … | Show a new QR code with android.pair and scan it again. |
pairing_timeout | The phone did not offer this pairing code in time. | Check that it is still running and reachable, then try once more. |
parent_missing | Something the request names does not exist or is not set up. | Create the parent directory first. |
parent_stopped | The parent job has already stopped. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
paste_unconfirmed | Android did not confirm the clipboard text. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
path_exists | Choose an empty report directory. | Choose another path, or pass overwrite:true. |
path_not_found | A path does not exist. | Check the path; it must be absolute and exist on this computer, or on the device for device paths. |
path_outside_roots | Under an agent policy other than full, the call would write outside the allowed roots (the data directory, the temp directory, the server's working directory, the policy's write_roots or TOMACCO_WRITE_ROOTS). | Write inside the project, or have the person add the folder to write_roots or TOMACCO_WRITE_ROOTS. |
platform_unsupported | The virtual iPhone runs iOS apps; pass platform ios. | Pass a platform the project and the device support; project.inspect lists the project's platforms. |
pmp_breakpoint_unsupported | Engine rejected the hardware instruction breakpoint. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_bus_fault | PMP accessed unsupported hardware or an unsupported register transaction. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_capture_pending | The virtual iOS device or its research engine refused the request or stopped answering. | Wait for the PMP job to finish before reading its capture. |
pmp_controller_required | The virtual iOS device or its research engine refused the request or stopped answering. | Build an engine with tomacco-pmp-asc-research and ASC controller tracing. |
pmp_cpu_identity_mismatch | Engine CPU identity differs from the requested configuration. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_cpu_policy_required | The virtual iOS device or its research engine refused the request or stopped answering. | Rebuild the engine with strict PMP system-register handling. |
pmp_debug_protocol | Expected a stopped CPU. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_debug_stop | CPU stopped at a different instruction. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_debug_timeout | Debugger response timed out. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_engine_required | The virtual iOS device or its research engine refused the request or stopped answering. | Build an engine with tomacco-pmp-research. |
pmp_memory_capture | Refusing to overwrite an existing RAM capture. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_memory_modified | RAM capture metadata is inconsistent. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_memory_unavailable | This job has no PMP RAM capture. | Run ios.emulator.pmp with capture_ram:true. |
pmp_observation_timeout | PMP observation expired; firmware boot is unverified. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_sysreg_fault | PMP accessed an unimplemented CPU system register. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
pmp_trace_required | PMP research requires architectural bus-fault tracing. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
policy_denied | The agent policy in force does not allow this operation for this caller. | Call agent.policy to see the policy; only the person can change it, from a terminal with settings.configure agent_policy. |
policy_invalid | settings.json has an agent_policy that cannot be read, so agent calls are blocked until it is fixed. | From a terminal, set a valid agent_policy with settings.configure. |
port_busy | Port … is already in use, perhaps by another Metro bundler. | Stop the other bundler, or its project.run job, then run again. |
preview_disconnected | Preview closed before replying. | Check that the dev server answers at the URL, then preview.reload or start the preview again. |
preview_unavailable | Cannot reach preview session …: … | Start tomacco --preview-session … |
process_missing | No Android process to attach; launch a debuggable build. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
profile_install_failed | The app's ProfileInstallReceiver did not install a baseline profile. | Install a release build that packages a baseline profile and depends on androidx.profileinstaller:profileinstaller. |
profile_mismatch | The request was refused; the message says why. | Check reports of the same application. |
profile_not_found | Unknown device profile: … | catalog.list names the device profiles. |
project_unrecognized | No supported project in … | Open a Flutter, Gradle, Swift, xtool, web or Xcode project, or add tomacco.json tasks. |
prompt_not_found | No MCP prompt has that name. | prompts/list names the prompts this server has. |
qmp_closed | Emulator closed its control channel. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
qmp_error | The virtual iOS device or its research engine refused the request or stopped answering. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
qmp_timeout | Emulator control channel stopped responding. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
qr_too_long | The pairing text does not fit a QR code. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
recording_active | A recording already runs for this device. | Stop it with action stop, or throw it away with action discard. |
recording_empty | Nothing was recorded; the recording keeps running. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
recording_not_active | No recording runs for this device. | Start one with action start. |
reload_failed | Port … did not answer as an HTTP server. | Read the message and the job's log (job.logs); fix the cause and try again. |
remote_not_found | Unknown remote workspace: … | remote.list names the configured remotes; add one with remote.configure. |
replay_failed | … from line … failed: … | Fix the cause and replay the rest, or edit the log. |
request_cancelled | The MCP client cancelled the request. | Nothing to fix; a job the request started keeps running, so check job.list before starting it again. |
research_bundle_required | The virtual iOS device or its research engine refused the request or stopped answering. | Prepare a full-system bundle with ios.emulator.prepare_research. |
research_environment | The virtual iOS device or its research engine refused the request or stopped answering. | Use ios.emulator.research for this full-system research bundle; it is not a command shell. |
research_hardware_missing | Engine does not support … | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
research_log_limit | Engine exceeded its log budget. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
research_serial_failed | Serial reader terminated unexpectedly. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
research_tools_missing | The virtual iOS device or its research engine refused the request or stopped answering. | Install the iOS research preparation tools. |
resource_not_found | No MCP resource has that URI. | resources/list and resources/templates/list name the resources this server has. |
response_too_large | Debugger response exceeds 2 MiB. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
result_not_found | No saved result has this result_id, or it has been removed. | Run the operation again; large results are saved under the result_id its answer names. |
result_too_large | The result is larger than inline_result_kib, so it was saved instead of returned inline. | Read it in pages with result.read and the result_id from the error. |
root_unavailable | The device has no root shell (Google Play images and phones), which the capture needs for tcpdump. | Use an emulator with a Google APIs or AOSP image. |
run_incomplete | The run has no finished report to add to the history. | Wait for the job to end, then record it. |
runtime_busy | Runtime input queue is full. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
runtime_configuration_conflict | This device already has a native session with different stream settings. | Reuse the existing session, or stop it before changing stream settings. |
runtime_directory | Runtime sockets require an owner-only directory. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
runtime_protocol | Runtime response exceeded its limit. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
runtime_required | No connected iPhone session for … | Start one with runtime.start platform=ios, device and runner_bundle_id, then run the scenario. |
runtime_start_failed | A display session with a device did not start or stopped answering. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
runtime_start_timeout | Native runtime is still starting; inspect runtime.state. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
runtime_stopped | Connection was cancelled. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
runtime_timeout | Device did not answer. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
runtime_unavailable | A display session with a device did not start or stopped answering. | Connect the Android runtime before enabling audio. |
scenario_failed | One or more device scenarios failed; inspect report.json and screenshots. | Read the job's report.json and screenshots for the failing step. |
scenario_missing | Something the request names does not exist or is not set up. | Save a scenario file in this workspace first. |
scrcpy_failed | Android display server exited: … | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
scrcpy_protocol | Expected scrcpy 4.1 display metadata. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
scrcpy_server_missing | The native Android view requires the scrcpy 4.1 server. | Install scrcpy 4.1 or pass the server JAR path to runtime.start. |
scrcpy_timeout | Android display server did not connect. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
screen_not_found | No screen with this id is in the run being reviewed. | List the ids with testing.baselines review. |
screen_unstable | The screen kept changing until the timeout, as a video, an animation or a spinner does. | details.last_changed_fraction says how much; use ignore for the part that moves, raise threshold, or wait for text instead. |
screenshot_missing | The screenshot the review names is gone from the run directory. | Run the scenario again with record_baselines. |
sdk_missing | Configure the Android SDK first. | Set android_sdk with settings.configure. |
sdk_platform_missing | Something the request names does not exist or is not set up. | Install an Android platform with android.sdk_install, then build again. |
secret_permissions | The App Store Connect .p8 key must be readable only by its owner. | chmod 600 the file. |
server_failed | … exited (…) before it listened on port … | Read the message and the job's log (job.logs); fix the cause and try again. |
server_timeout | Nothing listened on port … within … s. | Check that it is still running and reachable, then try once more. |
session_job_limit | This MCP session already runs as many jobs as jobs_per_session allows. | Wait for a job to end with job.wait, or cancel one with job.cancel. |
setting_not_applied | Android did not apply: … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
setting_unsupported | Switching airplane mode from adb needs Android 11 (API 30) or newer. | Older Android changes the language only for the whole device, in its Settings app. |
setup_failed | HOME is not set. | Run tomaccoctl setup from a normal login shell with HOME set. |
startup_unobserved | The screen did not change for … s after the app was opened. | Check that the app opens and draws on this phone (a screenshot after device.app launch), then try again. |
step_failed | … failed (…). | Read the message and the job's log (job.logs); fix the cause and try again. |
step_unsupported | Step …: … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
storage_flush_unverified | Engine did not confirm flushing the disposable image. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
store_key_incomplete | key_id, issuer_id and key_path go together. | Pass key_id, issuer_id and key_path together, or none of them. |
store_key_required | An upload needs key_id, issuer_id and key_path. | Create a team key under Users and Access > Integrations in App Store Connect, and the app record once. |
store_request_failed | Google Play request failed (HTTP …). | Read the HTTP status and Google's message; a 403 usually means the service account lacks permission for the app. |
store_response_invalid | Google did not return a bundle version code. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
swift_sdk_unconfigured | Swift SDK is not connected to an Android NDK. | Run swift.android_configure after installing the matching NDK. |
system_packages_missing | Missing: … | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
temporary_directory_changed | Temporary directory identity changed; preserved replacement. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
terminal_missing | Something the request names does not exist or is not set up. | Run xtool auth login in a terminal yourself; only the person signs in. |
test_runtime_required | The request was refused; the message says why. | Run portable Swift unit tests on Linux; Android behavior needs a device integration test. |
text_requires_accessibility | For non-ASCII text use runtime.input action=fill with the field coordinates; this replaces its full accessible value. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
text_timeout | The text did not appear, or go away, within the timeout. | Read details.seen for what the screen showed; check the text, try source ocr or hierarchy, raise the timeout, or look at a screenshot. |
text_too_long | Text through the clipboard is limited to {PASTE_LIMIT} bytes. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
text_unsupported | Text outside ASCII goes through the device clipboard, which needs the scrcpy 4.1 server. | Configure scrcpy with settings.configure, or run testing.setup and use testing.action with fill. |
tool_failed | A tool Tomacco ran exited with an error. | Read the tool's output in the message or the job's log (job.logs) and fix its cause. |
tool_missing | A tool the operation needs is not installed or not configured. | Install it as doctor's next_steps say, or point settings.configure executables at it, then call again. |
tool_output | A tool printed something Tomacco could not read. | Run the tool by hand in the project to see its own error; an outdated tool version is a common cause. |
tool_start_failed | A tool could not be started. | Check that the configured path is an executable file (settings.get, doctor) and that the host has the libraries it needs. |
tool_timeout | A tool Tomacco ran did not finish in its time. | Check that the device or network it needs is reachable, then try again; a job's timeout argument can give it longer. |
toolkit_missing | The pinned omarchy-apple-dev checkout has no … | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
toolkit_sdk_missing | The private toolchain has no current SDK. An SDK from ios.sdk_install does not count: the pinned xtool fork refuses its older stamp. | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
toolkit_toolchain_missing | The private omarchy-apple-dev toolchain is not installed. | Check the name or path in the message; the matching list operation (device.list, job.list, workspace.list, catalog.list) shows what exists, and doctor what is set up. |
trace_output | Unterminated trace processor CSV value. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
transport_failed | The MCP server could not write to its client. | Restart the client's connection to tomaccoctl mcp. |
ui_hierarchy_unavailable | … needs a UI hierarchy, and the virtual iPhone's guest tools do not report one. | Find text by its words instead (a selector with text or text_contains is read off the screenshot with OCR), or use screen.marks with source ocr, testing.run with tap, swipe, text, key, wait_screen and assert_screen steps, or ios.emulator.control with coordinates. |
unsafe_data_directory | The Tomacco data directory is not a directory owned by this user: … | Set TOMACCO_HOME to a directory you own. |
unsafe_runtime_directory | Runtime directory is not a private directory of this user: … | Remove it, or set TMPDIR to a directory only you can write. |
unsigned_artifact | Bundle signature could not be verified. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
unsupported_artifact | The input is of a kind this operation does not support. | Select an APK or AAB. |
unsupported_boot_display | This engine does not provide the guest boot framebuffer; rebuild the SPTM engine with Tomacco's patch. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
unsupported_boot_media | This engine cannot register the RAM image with IOMedia; rebuild the SPTM engine with Tomacco's patch. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
unsupported_codec | Android did not negotiate H.264. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
unsupported_device | A USB iPhone can be read but not tapped through the screen operations. | Use screen.export or device.screenshot to read it; taps need an Android device or the virtual iPhone. |
unsupported_engine | Guest commands require the Darwin/SPTM restore-shell backend. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
unsupported_export_version | The export was written in a newer format version than this Tomacco reads. | Update Tomacco, or export the screen again. |
unsupported_firmware | No matching board/variant erase identity in the firmware. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
unsupported_image | The input is of a kind this operation does not support. | Pass one of the supported kinds the message or the operation's schema names. |
unsupported_input | This action is not supported by the Android runtime. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
unsupported_key | Unknown Android key. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
unsupported_native_arch | The ELF architecture is not supported by the Android NDK debugger. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
unsupported_selector | The virtual iPhone has no UI hierarchy, so a selector there can only have text or text_contains, and index. | Use text or text_contains, or tap and swipe at pixel coordinates. |
unsupported_step | … is not available on the virtual iPhone. | Pass one of the supported kinds the message or the operation's schema names. |
unsupported_working_image | Working images require boot_media=true and an engine providing boot-storage. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
update_auto_off | Updates are not set to install by themselves. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_busy | An update is being installed right now. | Wait for the running installation to end; update.status shows it. |
update_check_failed | Checking for, downloading or installing an update did not work. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_checksum_mismatch | Refused the update: the package does not match its published checksum. Nothing was installed. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_download_failed | Downloading … failed: GitHub answered with status …. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_forced_off | Checking for, downloading or installing an update did not work. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_health_check_failed | Checking for, downloading or installing an update did not work. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_held | This version failed to install or was rolled back, so it is not installed by itself again. | Install it with update.apply manual:true only if the person wants to try it again. |
update_install_failed | The installer reported no journal for this installation. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_installer_failed | Checking for, downloading or installing an update did not work. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_invalid_package | Refused the update: …. Nothing was installed. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_no_package | Release … has no package …. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_no_release | No release is available yet. | Nothing to do until a release is published. |
update_not_available | No newer version is known yet. | Nothing to do: this is the newest known version. |
update_not_newer | Release … is not newer than …; an update never downgrades. | Nothing to do: an update never downgrades. |
update_nothing_to_roll_back | There is no installed update to roll back. | Nothing to do: no update was installed. |
update_off | Updates are turned off. Install one from the Settings, or pass manual when the user asked for it. | Pass manual:true only when the person asked for this update. |
update_offline | GitHub could not be reached during the download. This computer may be offline. | Connect to the network and try again. |
update_rollback_failed | The update failed (…) and restoring the previous version failed too (…). Its files are in the backup …. | Run the installer with --rollback and this backup ID, or install again. |
update_signature_invalid | Refused the update: …. Nothing was installed. | Correct the value the message names; tomaccoctl schema OPERATION lists accepted arguments. |
update_signing_key_missing | This build of {PRODUCT_NAME} has no release signing key, so it cannot verify an update and will not install one. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_too_large | Refused …: it exceeds the size limit. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_unsafe_package | Refused the update: …. Nothing was installed. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_unsigned | Refused the update: release … has no signature (….sig). Nothing was installed. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_unwritable | … cannot be written (…). | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
update_wrong_host | Refused the download address …: it is not this project's. | Read the message; update.status shows the update state, and Tomacco keeps the installed version when an update is refused. |
variable_missing | JDWP expressions support local variables and field paths. | Check the session with debug.list and its log; the app must be a debuggable build that is running. |
variant_required | This app has product flavors; name the build variant to install. | Pass variant with one of the build variants the message lists. |
verify_unreadable | Verification failed: … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
version_ambiguous | Expected exactly one …, found … | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
version_unsupported | Info.plist is not an XML property list. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
video_protocol | Invalid Android video packet length. | Check with device.list that the device is online, then stop the session with runtime.stop and start it again. |
worker_reaper_unavailable | The request was refused; the message says why. | Read the message, change what it names and try again; docs/troubleshooting.md lists known errors. |
worker_start_failed | A step Tomacco ran did not succeed. | Read the message and the job's log (job.logs); fix the cause and try again. |
workflow_needs_confirmation | A workflow.run step is destructive or publishes and has no confirm. | Tell the person what those steps delete, overwrite or publish, and set confirm:true on each only after they agree. |
workflow_step_failed | A workflow.run step failed or its job did not succeed; the later steps did not run. | Read details.steps for that step's error or job, fix the cause and run the workflow again. |
workflow_timed_out | workflow.run ran out of its timeout while following a job. | The job keeps running: follow it with job.wait, or stop it with job.cancel. |
working_image_changed | Working image was replaced before the job started. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
working_image_flush_failed | Engine did not confirm flushing the working image. | Read the message; ios.virtual.status and the job's log show the device's state, and docs/virtual-ios/troubleshooting.md lists known causes. |
workspace_busy | This project already has an active build or app session. | Wait for the named job with job.wait, or cancel it with job.cancel if the person agrees; do not work on a copy of the project. |
workspace_missing | Unknown workspace: … | workspace.list names the saved workspaces. |
xcode_import_failed | A step Tomacco ran did not succeed. | Read the message and the job's log (job.logs); fix the cause and try again. |
xtool_project_required | ship.sh builds xtool projects. | Create one with project.create kind xtool, or use project.import_xcode. |