Skip to main content

Documentation Index

Fetch the complete documentation index at: https://visorai.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Structured error codes

visor uses five top-level error codes.
Error codeMeaningTypical source
INPUT_ERRORThe request or scenario input is invalidValidation failures, schema issues
TARGET_ERRORThe runtime target could not be initializedDevice selection failures, Visor daemon not running, Appium unreachable, missing driver dependencies
ACTION_ERRORAn action or step failedUnsupported act variant, bad selector, invalid wait value, step timeout
ASSERTION_ERRORAn assertion failedVisibility target missing or unsupported assertion type
SYSTEM_ERRORReserved for system-level failuresNot currently emitted by the main flows

​
Where each error code appears

​
INPUT_ERROR

Common cases:
  • scenario parsing fails
  • scenario validation fails
  • required schema fields are missing
  • unsupported legacy platform value in meta.platform

​
TARGET_ERROR

Common cases:
  • no running device is detected when a runtime command needs one
  • multiple running devices are detected in a non-interactive shell without --device
  • Visor daemon is not running for a runtime command
  • Appium server cannot be reached when running visor start
  • driver dependencies are not available in the runtime environment
  • runtime adapter cannot be initialized

​
ACTION_ERROR

Common cases:
  • direct action command throws an exception
  • a scenario step throws an exception
  • a step exceeds the configured timeout
  • act receives an unsupported operation
  • tap receives invalid argument combinations

​
ASSERTION_ERROR

Common cases:
  • a visible assertion did not find the target
  • an unsupported assertion type was evaluated

​
Exit codes

visor uses these process exit codes.
Exit codeMeaning
0Success
1Input failure, target initialization failure, or direct action failure
2Scenario run completed but one or more steps or assertions failed
3Benchmark did not meet the threshold or one or more benchmark iterations failed

​
Command-specific behavior

​
Validation

  • returns 0 when the scenario is valid
  • returns 1 when validation or parsing fails

​
Direct action commands

  • return 0 on success
  • return 1 when the action fails

​
Scenario runs

  • return 0 when all steps and assertions pass
  • return 2 when the run completes with step or assertion failures
  • return 1 when setup fails before execution starts

​
Benchmarks

  • return 0 when the score meets the threshold and failures are 0
  • return 3 when the threshold is not met or any iteration failed
  • return 1 when scenario validation or runtime preflight fails before the benchmark loop

​
Error payload design

Every failure response includes a structured error payload with:
  • code
  • message
  • likely_cause
  • next_step
This makes failures usable for both people and automated agents.