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.

A command box branches into four outcomes: exit 0 with JSON on stdout, exit 2 with an error object on stderr, exit 1 when a test failed, and exit 130 when interrupted. Below, the exit 2 object with ok false, error_code, error and hint. A command box branches into four outcomes: exit 0 with JSON on stdout, exit 2 with an error object on stderr, exit 1 when a test failed, and exit 130 when interrupted. Below, the exit 2 object with ok false, error_code, error and hint.
Every expected failure has the same shape, so one branch handles them all.

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.

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 serve do 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 detach puts 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.

  1. 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.

{"ok": false, "error_code": "ambiguous_target", "error": "2 ready targets; pass --target (or --platform)", "hint": "Candidates: android:emulator-5554, android:emulator-5556", "candidates": [{"platform": "android", "target_id": "emulator-5554"}, {"platform": "android", "target_id": "emulator-5556"}]}

What to look at. ambiguous_target is the branch. candidates gives your agent the exact values to pass to --target.

Goal: confirm that a step without its consent flag changes nothing, and that the journal still shows it.

  1. Start a session.

    The journal starts with it.

    autonom session start --serial emulator-5554 --app-id com.example.app
  2. Start the proxy without its flag.

    The step is refused before anything runs, with exit code 2.

    autonom network start
  3. 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.

{ "ok": true, "count": 2, … { "seq": 2, … "verb": "network start", … "ok": false, "origin": "agent", "error_code": "consent_required"

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
{"ok": false, "error_code": "consent_required", "error": "refused without explicit consent — mitm_proxy on 127.0.0.1:auto: start a man-in-the-middle proxy that decrypts and records this session's HTTP(S) traffic to disk", "hint": "Re-run with the required flag(s): --i-understand-mitm. On an interactive terminal you will also be asked to type the confirmation phrase.", "operation": "mitm_proxy", "target": "127.0.0.1:auto"}
Show full output
{ "ok": true, "count": 2, "total_matched": 2, "truncated": false, "entries": [ { "seq": 1, "ts": "…", "kind": "action", "verb": "session start", "argv": [ "--adb", "…/tests/fakes/fake_adb.py", "session", "start", "--serial", "emulator-5554", "--app-id", "com.example.app" ], "ok": true, "origin": "agent" }, { "seq": 2, "ts": "…", "kind": "action", "verb": "network start", "argv": [ "--adb", "…/tests/fakes/fake_adb.py", "network", "start" ], "ok": false, "origin": "agent", "error_code": "consent_required" } ], "journal": "…/.autonom/sessions/s_…/journal.ndjson"}
A flowchart: a privileged step checks for its flag, then on a terminal for the typed phrase. A missing flag leads to consent_required, a wrong phrase to consent_declined. Only after both does the change run and the grant get logged. A flowchart: a privileged step checks for its flag, then on a terminal for the typed phrase. A missing flag leads to consent_required, a wrong phrase to consent_declined. Only after both does the change run and the grant get logged.
A step runs only after its flag, and on a terminal its phrase.

Read a validation error by its position

Goal: find the exact line that makes a flow file invalid.

  1. 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.

{"ok": false, "error_code": "flow_selector_invalid", "error": "…/flows/smoke.yaml:9:14: unknown match mode 'exactly'", "hint": "Did you mean 'exact'? Match modes: caseInsensitiveExact, contains, exact, regex.", "file": "…/flows/smoke.yaml", "line": 9, "column": 14}

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
1 schema: autonom.dev/flow/v1 2 appId: com.example.app 3 name: Smoke 4 --- 5 - launchApp 6 - tapOn: 7 selector: 8 text: Add to cart 9 match: exactly10 - assertVisible:11 selector:12 id: cart_badge13 timeoutMs: 3000

Fail cleanly on a machine with no devices

Goal: see what a command says on a machine with no device tools at all.

  1. 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.

{"ok": false, "error_code": "no_target", "error": "no ready target found", "hint": "Start an emulator or boot a simulator, then run 'autonom devices'."}

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.

S=$PWD W=/tmp/autonom-safetyrm -rf $W && mkdir -p $W/flowsexport AUTONOM_HOME=$W/.autonomautonom() { python3 $S/scripts/autonom.py --adb $S/tests/fakes/fake_adb.py --simctl $S/tests/fakes/fake_simctl.py "$@"; }echo '{"devices": [["emulator-5554", "device", "product:sdk_gphone64_arm64"], ["emulator-5556", "device", "product:sdk_gphone64_arm64"]]}' > $W/two.jsonAUTONOM_FAKE_STATE=$W/two.json autonom --platform android ui treeautonom session start --serial emulator-5554 --app-id com.example.appautonom network startautonom journalls -A $AUTONOM_HOME/sessions/*/networkcd $Wprintf '%s\n' 'schema: autonom.dev/flow/v1' 'appId: com.example.app' 'name: Smoke' '---' '- launchApp' '- tapOn:' ' selector:' ' text: Add to cart' ' match: exactly' '- assertVisible:' ' selector:' ' id: cart_badge' ' timeoutMs: 3000' > flows/smoke.yamlautonom flow check flows/smoke.yamlenv -i PATH= AUTONOM_HOME=$W/bare "$(command -v python3)" $S/scripts/autonom.py screenshot

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: false with ok: true is 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 .gitignore protects a copy. Delete them when the work is done.

Reference

The commands that gate, record and undo what Autonom changes.

CommandWhat it does
autonom doctor --strictExits 1, with ok: false and strict_failures, when the machine is not ready.
autonom network start --i-understand-mitmStarts the capture proxy. The flag is needed every time.
autonom network attach --i-understand-mitmRoutes the device through the proxy. Installing a CA also needs --install-ca.
autonom network detachPuts the device's proxy setting back as it was.
autonom journalThe session's timeline, failures and refusals included.
autonom processesEvery process Autonom started on this machine.
autonom cleanupStops leftover processes, each only after checking it still runs the recorded command.
autonom session stopStops the proxy, the streams and the session's processes.
xcrun simctl keychain <udid> resetRemoves 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_selector

When: A selector matched more than one node, and the command acts on one.

Do: List the matches with --all, then pass --index or a tighter selector.

Read and drive the screen

ambiguous_target

When: More than one target is ready, and none was named.

Do: Pass one of the candidates with --target, or narrow with --platform.

Sessions and targets

app_not_allowed

When: 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.

Ticket pre-test

app_not_debuggable

When: Android refused run-as, so the app's files cannot be read.

Do: Install a debug build of the app.

Device state

app_not_installed

When: 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.

Sessions and targets

backend_failed

When: 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.

Network

budget_exhausted

When: 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.

Ticket pre-test

ci_destination_failed

When: 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 run and ci finalize report it inside publication and keep their verdict.

Do: Publish to a new, empty directory, check the endpoint, or run ci finalize first.

CI campaigns

When: On a terminal, the typed phrase did not match. Nothing changed.

Do: Run the command again and type the phrase exactly.

Network

When: 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.

Network

control_generation_stale

When: 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.

Sessions and targets

control_held

When: Someone else holds the device’s control lease: a person in Mobile Canvas, or another agent. Nothing ran.

Do: Wait until autonom control status reads free, or ask the holder to release it.

Sessions and targets

control_lease_expired

When: Your lease ran out before this action. Nothing ran.

Do: Renew before the expiry with autonom control renew, or acquire again, with a longer --ttl if needed.

Sessions and targets

control_not_held

When: Your claim names a lease you do not hold, or there is none.

Do: Acquire the lease, or drop the claim.

Sessions and targets

coordinate_space_mismatch

When: 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.

Read and drive the screen

draft_unavailable

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.

Ticket pre-test

element_offscreen

When: The matched node is not on screen, so nothing was tapped.

Do: Scroll it into view, then select it again.

Read and drive the screen

evidence_ref_unknown

When: 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.

Ticket pre-test

flow_assertion_timeout

When: 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.

Flows

flow_command_invalid

When: A value given to a command is malformed, such as an --env without =. Nothing ran.

Do: Pass --env KEY=VALUE, as the error quotes.

CI campaigns

flow_file_not_found

When: A flow file does not exist at the path given.

Do: Check the path, then run flow check on it.

Flows

flow_replay_step_not_reached

When: 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.

Replay

flow_requirements_unmet

When: 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.

Capabilities

flow_secret_undefined

When: A secret the run needs, named by --secret or 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.

Replay

flow_selector_invalid

When: 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.

Flows

forbidden_action

When: 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.

Ticket pre-test

invalid_simulator_action

When: A simulator control got an action it does not have.

Do: Pick one from valid_actions in the error.

Device state

ios_hid_framework_missing

When: idb's companion cannot load the Simulator's input framework, as on Xcode 27.

Do: Upgrade idb-companion, or install AXe.

Install

no_active_session

When: 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.

Sessions and targets

no_matching_node

When: No node on screen matched the selector.

Do: Read the tree and match what it says. The label may be in --desc.

Read and drive the screen

no_open_check

When: The check named in pretest check end is not open, or has already ended.

Do: Run autonom pretest check list. To add to an ended check, record a finding.

Ticket pre-test

no_target

When: 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.

Sessions and targets

physical_device_attach_unsupported

When: 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.

Network

pretest_already_active

When: A pre-test is already active in this session.

Do: Pack it, or close it with autonom pretest stop, then start the next one.

Ticket pre-test

pretest_finalized

When: The pre-test is packed, and a pack never changes.

Do: Use pretest review … more-checks or pretest rerun for a linked child pre-test.

Ticket pre-test

profile_invalid

When: The app profile cannot be read, has unknown keys, names a variable outside AUTONOM_ or PRETEST_, or holds something shaped like a credential.

Do: Fix the key path named in failures; put secrets in the environment, never in the profile.

Ticket pre-test

replay_manifest_invalid

When: 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.

Replay

report_bundle_finalized

When: The --out of report bundle holds 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 bundle

report_integrity_failed

When: 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; failures names each file that changed.

Agent report

selector_index_out_of_range

When: --index is past the number of matches.

Do: Count the matches with --all, then fix the index.

Read and drive the screen

session_already_active

When: A session already owns the target.

Do: Stop it first with autonom session stop.

Sessions and targets

session_stopped

When: 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.

Sessions and targets

session_target_mismatch

When: 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.

Sessions and targets

ui_action_uncertain

When: 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.

Read and drive the screen

unsupported_capability

When: 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.

Device state

unsupported_on_platform

When: 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.

Read and drive the screen

usage_error

When: The command line is wrong: an unknown command or flag, or flags that clash.

Do: Read hint; it holds the usage line.

How a failure looks

Warning codes

A warning rides in the warnings list of a successful answer. The command still did its work.

companion_left_running

When: Stop found an idb companion the session did not start, and left it running.

Do: Stop it with kill if nothing else uses the Simulator.

Sessions and targets

cpu_stale

When: A CPU figure came from an old sampling window.

Do: Measure a series under a fixed flow before you make a claim.

Performance and memory

device_proxy_changed_externally

When: 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.

Network

evidence_write_failed

When: 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.

Evidence

flag_ignored_on_platform

When: A flag does nothing on this platform, such as --activity on iOS.

Do: Drop the flag. The hint says why it has no effect.

Sessions and targets

label_is_in_desc

When: --text matched nothing, but the same value matches the description.

Do: Retry with --desc, as the hint shows.

Read and drive the screen

log_filter_degraded

When: 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.

Evidence

no_focused_field

When: No field had keyboard focus, so the typed text may be lost.

Do: Tap the field first, then type, and confirm with ui find.

Read and drive the screen

no_frames

When: gfxinfo counted no frames, as for a Flutter app.

Do: For Flutter, summarize frame timings with flutter-summary.

Performance and memory

override_path_missing

When: An AUTONOM_* override points at a binary that does not exist.

Do: Unset it, or point it at a binary that exists.

Install

persistent_mocks_active

When: Mock rules from earlier are still switched on, so matching responses will be faked.

Do: Review them, then run autonom network mock disable --all.

Network

screenshot_shows_mocked_data

When: A screenshot was taken while a mock rule was active.

Do: Never present it as real backend behavior.

Evidence

session_unreadable

When: session list found 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.

Sessions and targets

signal_unstable

When: 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.

Evidence

sparse_accessibility_tree

When: On iOS, fewer than three meaningful nodes were found.

Do: Add accessibility labels in the app, or fall back to a screenshot.

Read and drive the screen

url_opened_chooser

When: 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.

Device state

Android and iOS differences

The two platforms differ in what capture can prove and what teardown undoes.

CapabilityAndroidiOS Simulator
Network captureYes, through the emulator's host addressPartly: its traffic looks like your Mac's
A physical deviceRefused, with physical_device_attach_unsupportedNot a target: Autonom drives the Simulator only
Installing a CAYes on an emulator; a Play Store image fails with backend_failedStays after detach, until you reset the keychain
Pinch, rotate, shakeRefused, with unsupported_on_platformRefused the same way

Next steps

You can read every failure by its code and know what consent protects.

Search documentation

Type to find a guide.

↑ ↓ to move · Enter to open · Esc to close