Safety and errors
Every failure comes back with a stable code your agent can branch on. Risky steps need consent every time, and credentials are masked before anything reaches disk.
Try it autonom network start
How it works
A command prints one JSON document on stdout and exits 0. An expected failure prints one error object on stderr instead and exits 2. The object always has ok, error_code, error and hint.
Four streaming modes print one JSON object per line instead: flow run --events, logs follow, network requests follow and journal --follow. You opt in to each. tour --human prints Markdown for a person.
Your agent branches on error_code, never on the text. Codes may be added, but a code never changes meaning and is never removed. Every code the docs show is listed below.
Exit 1 means a test failed: a flow step, or a screen that never settled. doctor exits 0 even when tools are missing, unless you pass --strict. Exit 130 means you interrupted the command.
Warnings are softer. They sit in a warnings list, each with a code, and the command still succeeds.
Consent is asked every time
Some steps change trust or traffic: starting the network proxy, attaching a device, installing a CA. Each needs its own flag on every run. On an interactive terminal, you also type a confirmation phrase.
A refusal happens before anything runs, so a refused step changed nothing. No setting, file or earlier approval stands in for consent.
What stays protected
Loopback only. The proxy listens on 127.0.0.1, with no flag to widen it. Mobile Canvas and
report servedo too.Masked before written. Sensitive headers and credential-like body fields are masked at capture. The saved files never held them.
Owner-only files. Only your user can read the network folder and flow files. Capture refuses a folder anyone can write to.
Your Mac's settings stay put. Autonom never changes the Mac's own network settings.
Teardown restores.
network detachputs back the exact proxy setting it found.
Examples
Every output here comes from Autonom's test device, so you can reproduce it without an emulator. The commands are in Reproduce these outputs, after the examples.
Branch on the code when the target is ambiguous
Goal: see what your agent gets when two emulators are ready and no target is named.
- Run any command that needs a target.
Autonom refuses to guess between the two.
autonom ui tree
You should see one error object on stderr, with exit code 2.
What to look at. ambiguous_target is the branch. candidates gives your agent the exact values to pass to --target.
See a privileged step refused, and kept on the record
Goal: confirm that a step without its consent flag changes nothing, and that the journal still shows it.
- Start a session.
The journal starts with it.
autonom session start --serial emulator-5554 --app-id com.example.app - Start the proxy without its flag.
The step is refused before anything runs, with exit code 2.
autonom network start - Read the journal.
Every command is recorded, refusals included.
autonom journal
You should see the refusal in the journal as ok: false with its code.
What to look at. The refused step is on the record, even if your agent never mentions it. The refusal itself, consent_required, names the flag to add. In the test run, the session's network folder stayed empty.
Show the refusal
Show full output
Read a validation error by its position
Goal: find the exact line that makes a flow file invalid.
- Check the flow file.
Line 9 asks for a match mode that does not exist.
autonom flow check flows/smoke.yaml
You should see the file, line and column, and a hint with the valid match modes.
What to look at. The error object adds file, line and column to the usual keys. The hint lists every valid mode, so the fix is one word: exact.
Show the flow file
Fail cleanly on a machine with no devices
Goal: see what a command says on a machine with no device tools at all.
- Take a screenshot.
There is no emulator, no Simulator and no adb.
autonom screenshot
You should see one error code and a hint, and no traceback.
What to look at. The hint names the next command. Your agent can follow it instead of guessing why nothing happened.
Reproduce these outputs
From the root of an Autonom checkout at tag v0.36.1 (commit ca2a280), in bash or zsh. Autonom's test device stands in for two emulators, and its test simctl stands in for Xcode, so the script needs neither a device nor Xcode; --platform android limits the choice to the two emulators. The last command runs on an empty PATH, like a machine with no device tools. Session ids and times differ on every run, and paths are shortened to … on the page.
Good to know
Branch on error_code, never on the text. The message may change. The code does not.
The control lease is coordination, not security. It keeps a person and cooperating agents of one user from driving one device at once. Any process of that user can take over, so it does not stop a misbehaving agent. See Sessions and targets.
Exit 0 does not prove a tap changed anything. Compare before and after screenshots or trees.
verified means read back.
verified: falsewithok: trueis a success whose effect is unconfirmed.Consent is never remembered. An approval earlier in the same session does not carry to the next command.
Credentials are masked before they are written. Not just before they are shown, so the files on disk never held them.
A mocked screenshot is flagged. It carries screenshot_shows_mocked_data. Never present it as real backend behavior.
Pinning is not bypassed. Use a debug build with certificate pinning relaxed, and say plainly when traffic cannot be read.
Session files are sensitive. They live outside any repository, so no
.gitignoreprotects a copy. Delete them when the work is done.
Reference
The commands that gate, record and undo what Autonom changes.
| Command | What it does |
|---|---|
autonom doctor --strict | Exits 1, with ok: false and strict_failures, when the machine is not ready. |
autonom network start --i-understand-mitm | Starts the capture proxy. The flag is needed every time. |
autonom network attach --i-understand-mitm | Routes the device through the proxy. Installing a CA also needs --install-ca. |
autonom network detach | Puts the device's proxy setting back as it was. |
autonom journal | The session's timeline, failures and refusals included. |
autonom processes | Every process Autonom started on this machine. |
autonom cleanup | Stops leftover processes, each only after checking it still runs the recorded command. |
autonom session stop | Stops the proxy, the streams and the session's processes. |
xcrun simctl keychain <udid> reset | Removes a CA from a Simulator. network detach leaves it there on purpose. |
Error codes
Each code below appears in these docs. Your agent reads it from error_code in the error object.
ambiguous_selectorWhen: A selector matched more than one node, and the command acts on one.
Do: List the matches with
--all, then pass--indexor a tighter selector.ambiguous_targetWhen: More than one target is ready, and none was named.
Do: Pass one of the
candidateswith--target, or narrow with--platform.app_not_allowedWhen: A pre-test is active, and opening a link or launching, stopping or clearing an app would reach an app outside
--allow-app. No input was sent.Do: End the check blocked. Only the person who asked for the pre-test widens the list.
app_not_debuggableWhen: Android refused
run-as, so the app's files cannot be read.Do: Install a debug build of the app.
app_not_installedWhen: The app is not installed on the target, or no app id was given.
Do: Check the package id, or start the session with
--app-id.backend_failedWhen: A device tool that Autonom calls, such as adb, failed.
Do: Read
error. A CA install fails this way on a Play Store image; use another.budget_exhaustedWhen: The pre-test used up its action or minute budget. No input was sent.
Do: Stop driving, end the open check blocked, pack and report it.
ci_destination_failedWhen: A campaign could not be published: the directory is not empty or is not a directory, the HTTP endpoint did not accept it, or the campaign was never finalized.
ci runandci finalizereport it insidepublicationand keep their verdict.Do: Publish to a new, empty directory, check the endpoint, or run
ci finalizefirst.consent_declinedWhen: On a terminal, the typed phrase did not match. Nothing changed.
Do: Run the command again and type the phrase exactly.
consent_requiredWhen: A step that changes trust or traffic ran without its flag. Nothing ran.
Do: Add the flag the hint names, such as
--i-understand-mitm.control_generation_staleWhen: Your lease was replaced, usually by a person’s Take over; your claim names an older generation. Nothing ran.
Do: Acquire the lease again. Never replay an input whose outcome you did not see.
control_heldWhen: Someone else holds the device’s control lease: a person in Mobile Canvas, or another agent. Nothing ran.
Do: Wait until
autonom control statusreads free, or ask the holder to release it.control_lease_expiredWhen: Your lease ran out before this action. Nothing ran.
Do: Renew before the expiry with
autonom control renew, or acquire again, with a longer--ttlif needed.control_not_heldWhen: Your claim names a lease you do not hold, or there is none.
Do: Acquire the lease, or drop the claim.
coordinate_space_mismatchWhen: A tap point lies outside the target's screen.
Do: Take the point from the tree's bounds, in points on iOS, or tap by selector instead.
When: A finding or check has nothing to replay: no check, no replayable action, or no flow or draft on this machine. Nothing was written.
Do: Drive the check by selector taps and a closing
ui find, or name another finding.element_offscreenWhen: The matched node is not on screen, so nothing was tapped.
Do: Scroll it into view, then select it again.
evidence_ref_unknownWhen: A finding cites evidence that names no artifact of the session. Nothing was written.
Do: List the artifacts, for example with
autonom shots list, and use the real id.flow_assertion_timeoutWhen: An asserted element never appeared within the step's
timeoutMs.Do: Replay up to that step, read the tree, and check the label the screen really shows.
flow_command_invalidWhen: A value given to a command is malformed, such as an
--envwithout=. Nothing ran.Do: Pass
--env KEY=VALUE, as the error quotes.flow_file_not_foundWhen: A flow file does not exist at the path given.
Do: Check the path, then run
flow checkon it.flow_replay_step_not_reachedWhen: A replay or an agent report was asked for a step the run does not have, so nothing ran. Or a replay ran the whole flow without that step ending as it did in the source run, for example because the failure no longer happens. A replay that fails before it reaches its step is not this error: it exits 1 with status
failed.Do: Pass the step's runtime index or stable step id from the run's report. If the flow ran, the step ended differently this time; inspect the new run.
flow_requirements_unmetWhen: The target lacks a capability the flow requires, so the run stopped before its first step.
Do: Read
capability_details, then provide the capability, such as the capture proxy, or pick another target.flow_secret_undefinedWhen: A secret the run needs, named by
--secretor recorded by the source run of a replay, is not set in the environment.Do: Export the variables the error names, then run again. Autonom records only their names, but a screen that shows a typed value keeps it in screenshots, screen trees and logs.
flow_selector_invalidWhen: A selector in a flow file is malformed, such as an unknown match mode.
Do: Fix the line the error names; the hint lists the valid values.
forbidden_actionWhen: A pre-test is active, and the tap target matches
--forbid-text, or the screen under the point could not be read. No input was sent.Do: Do not retry another way. End the check blocked, or take a safe path.
invalid_simulator_actionWhen: A
simulatorcontrol got an action it does not have.Do: Pick one from
valid_actionsin the error.ios_hid_framework_missingWhen: idb's companion cannot load the Simulator's input framework, as on Xcode 27.
Do: Upgrade idb-companion, or install AXe.
no_active_sessionWhen: A command needs a current session, and none is running.
Do: Start one with
autonom session start, or name a session or a bundle where the command takes one.no_matching_nodeWhen: No node on screen matched the selector.
Do: Read the tree and match what it says. The label may be in
--desc.no_open_checkWhen: The check named in
pretest check endis not open, or has already ended.Do: Run
autonom pretest check list. To add to an ended check, record a finding.no_targetWhen: No ready target was found, or a command needed an app id or target it did not get.
Do: Start an emulator or boot a Simulator, then run
autonom devices.physical_device_attach_unsupportedWhen: Network capture or a CA install was asked of a physical Android device.
Do: Use an emulator. A physical device cannot reach the loopback proxy.
pretest_already_activeWhen: A pre-test is already active in this session.
Do: Pack it, or close it with
autonom pretest stop, then start the next one.pretest_finalizedWhen: The pre-test is packed, and a pack never changes.
Do: Use
pretest review … more-checksorpretest rerunfor a linked child pre-test.profile_invalidWhen: The app profile cannot be read, has unknown keys, names a variable outside
AUTONOM_orPRETEST_, or holds something shaped like a credential.Do: Fix the key path named in
failures; put secrets in the environment, never in the profile.replay_manifest_invalidWhen: The flow file a replay source points at is gone.
Do: Restore the file at the path the error names, or replay from a report bundle, which keeps its own copy.
report_bundle_finalizedWhen: The
--outofreport bundleholds a finalized bundle of another run, or other files. Nothing was written.Do: Choose a new, empty directory for every run. The same run into its own bundle is a safe retry.
report_integrity_failedWhen: A report bundle has no manifest, or a file in it no longer matches its recorded digest. Nothing was read from it.
Do: Use the original bundle;
failuresnames each file that changed.selector_index_out_of_rangeWhen:
--indexis past the number of matches.Do: Count the matches with
--all, then fix the index.session_already_activeWhen: A session already owns the target.
Do: Stop it first with
autonom session stop.session_stoppedWhen: A command named a stopped session, which allows only reads.
Do: Start a new session, or use the stopped one only for its journal, shots, logs and report.
session_target_mismatchWhen: A command's target flags name another device than the session it is bound to.
Do: Drop the flags, or name the session on that target.
ui_action_uncertainWhen: An input may or may not have reached the device; its answer was lost.
Do: Look at the screen before anything else, and never repeat the input automatically.
unsupported_capabilityWhen: The target cannot do what was asked, such as a capability a flow requires.
Do: Check what this machine and target support with
autonom doctor.unsupported_on_platformWhen: The command does not exist on this platform, such as pinch, rotate or shake.
Do: Run it on the platform that has it, or do the same thing another way.
usage_errorWhen: The command line is wrong: an unknown command or flag, or flags that clash.
Do: Read
hint; it holds the usage line.
Warning codes
A warning rides in the warnings list of a successful answer. The command still did its work.
companion_left_runningWhen: Stop found an idb companion the session did not start, and left it running.
Do: Stop it with
killif nothing else uses the Simulator.cpu_staleWhen: A CPU figure came from an old sampling window.
Do: Measure a series under a fixed flow before you make a claim.
device_proxy_changed_externallyWhen: Stopping capture found the emulator proxy changed outside Autonom, no longer pointing at the capture.
Do: Nothing to undo: Autonom left the setting as it found it. Check it if the device has no network.
evidence_write_failedWhen: An action ran, but its detail file could not be saved.
Do: Check the disk and the session folder. The input was not repeated, so look at the screen before you act again.
flag_ignored_on_platformWhen: A flag does nothing on this platform, such as
--activityon iOS.Do: Drop the flag. The hint says why it has no effect.
label_is_in_descWhen:
--textmatched nothing, but the same value matches the description.Do: Retry with
--desc, as the hint shows.log_filter_degradedWhen: Logs could not be narrowed to the app by its uid, so a weaker filter ran.
Do: Launch the app first, or use a device on API 31 or later.
no_focused_fieldWhen: No field had keyboard focus, so the typed text may be lost.
Do: Tap the field first, then type, and confirm with
ui find.no_framesWhen: gfxinfo counted no frames, as for a Flutter app.
Do: For Flutter, summarize frame timings with
flutter-summary.override_path_missingWhen: An
AUTONOM_*override points at a binary that does not exist.Do: Unset it, or point it at a binary that exists.
persistent_mocks_activeWhen: Mock rules from earlier are still switched on, so matching responses will be faked.
Do: Review them, then run
autonom network mock disable --all.screenshot_shows_mocked_dataWhen: A screenshot was taken while a mock rule was active.
Do: Never present it as real backend behavior.
session_unreadableWhen:
session listfound a session record it could not read, and left it out.Do: Check or remove that session folder; the other sessions are listed as usual.
signal_unstableWhen: Pinned signal bars cannot be read back, or the pin was not sent again.
Do: If the pin was not sent, pin the status bar again before you capture.
sparse_accessibility_treeWhen: On iOS, fewer than three meaningful nodes were found.
Do: Add accessibility labels in the app, or fall back to a screenshot.
url_opened_chooserWhen: A URL opened the system chooser, not an app. The command still exited 0.
Do: Verify the App Link, or pick the app in the chooser.
Android and iOS differences
The two platforms differ in what capture can prove and what teardown undoes.
| Capability | Android | iOS Simulator |
|---|---|---|
| Network capture | Yes, through the emulator's host address | Partly: its traffic looks like your Mac's |
| A physical device | Refused, with physical_device_attach_unsupported | Not a target: Autonom drives the Simulator only |
| Installing a CA | Yes on an emulator; a Play Store image fails with backend_failed | Stays after detach, until you reset the keychain |
| Pinch, rotate, shake | Refused, with unsupported_on_platform | Refused the same way |
Next steps
You can read every failure by its code and know what consent protects.