Skip to main content

​
Structured error codes

visor uses five top-level error codes.
Error codeMeaningTypical source
INPUT_ERRORThe request or scenario input is invalidValidation failures, schema issues, invalid platform
TARGET_ERRORThe runtime target could not be initializedAppium unreachable, missing driver dependencies, unsupported platform
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 platform value in meta.platform

​
TARGET_ERROR

Common cases:
  • Appium server cannot be reached in real runtime mode
  • 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.