Errors and exit codes

​

Structured error codes

Visor uses five top-level error codes.

​

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.

​

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.