Error levels

From John's wiki
Jump to navigation Jump to search

I should have done this a long time ago. I'm going to start allocating standard error levels for my own use.

To be clear, these are process error levels, also known as exit status and error code. I endeavour to allocate particular error levels for my own use in the range [10, 100), comfortably in two-digit territory.

Note that I mostly program in PHP, so 'error', 'exception', and 'assertion' are particular to PHP, but they might apply in other contexts.

My error levels

These are some notes about error levels specifically nominated by me.

Error Level Category Constant HTTP Meaning
10 cannot continue EXIT_CANNOT_CONTINUE 202 cannot continue; but nothing is abnormal or wrong
40 user error EXIT_USER_ERROR 400 user error; invalid command-line or options
41 user error EXIT_NO_FILE 400 no file; file/directory path not nominated
42 user error EXIT_WRONG_FILE 400 wrong file; user nominated file (or directory) missing
43 user error EXIT_BAD_FILE 403 invalid file; user nominated file (or directory) cannot be accessed due to invalid permissions
60 environment error EXIT_BAD_ENVIRONMENT 503 invalid run-time environment; cannot run
61 environment error EXIT_FILE_MISSING 503 system file missing; a file (or directory) that is expected to always be available is not available
62 environment error EXIT_NO_ACCESS 503 no access; file (or directory) that should be accessible cannot be accessed due to invalid permissions
63 environment error EXIT_BAD_CONFIG 503 invalid configuration; config file missing or invalid
76 environment error EXIT_NO_SERVICE 503 no service; cannot establish connection to a required service
77 environment error EXIT_NO_DATABASE 503 no database; cannot establish connection to a required database
78 environment error EXIT_EXHAUSTED 507 resources exhausted; out of memory, disk space, inodes, etc
79 environment error EXIT_OFFLINE 503 system offline; as configured by administrator
80 program error EXIT_PROBLEM 500 software problem; unhandled and fatal situation encountered
81 program error EXIT_ERROR 500 program error; error caused process termination
82 program error EXIT_EXCEPTION 500 program exception; unhandled exception caused process termination
83 program error EXIT_ASSERT 500 assertion violation; assertion violation caused process termination
84 program error EXIT_TEST_FAILED 500 test failed; unit-test did not succeed
89 program error EXIT_INVALID 500 invalid error level; the programmer nominated an invalid error level and the host exited with 89 instead
90 special purpose EXIT_SPECIAL_SUCCESS 204 special operation successful; used for safety (in case improperly invoked)
98 special purpose EXIT_OPTIONS_LISTED 200 program options listed; use when programs can be invoked to list their options in a machine readable format
99 special purpose EXIT_HELP 200 help or version number requested

Other error levels

These are some notes about how other software uses error levels.

Error Level Convention Category Constant HTTP Meaning
0 success EXIT_SUCCESS 200 success!
1 generic EXIT_GENERIC_1 404 the generic "some problem occurred" value, prefer something more specific
2 generic EXIT_GENERIC_2 404 incorrect usage or invalid arguments, the 404 of error levels
126 UNIX UNIX EXIT_NO_PERMISSION 403 command was found but could not be executed due to permissions
127 UNIX UNIX EXIT_NO_COMMAND 404 command not found or could not be executed
128 UNIX UNIX EXIT_TERMINATED_BY_SIGNAL 500 process terminated by signal
130 UNIX UNIX EXIT_TERMINATED_BY_CTRLC 500 process terminated by Ctrl+C
255 generic EXIT_GENERIC_255 404 the other generic "some problem occurred" value, prefer something more specific

Error level range

The errors are in increasing order of should-not-happenness. Basically:

  • logic error: cannot continue now, but nothing is wrong
  • input error: invalid data
  • user error: invalid options
  • environment error: an environment problem, cannot connect to service or incompatible versions etc
  • program error: shouldn't happen, a situation the code hasn't handled yet

Whether it's an input error, user error, or environment error is basically a decision for you to make. It's not super important which number you allocate, especially when multiple categories might apply. It's probably best if you try to blame the program or environment more and the user less.

Note that special purpose "success" codes are only used in situations where you want to protect the user from making a mistake. So if a version number is printed because there was a --version command-line argument; or help was printed because there was a --help command-line argument; or if a machine-readable list of options was requested and supplied; then we exit with a non-zero error level even though technically we haven't "failed", we just might have done something by accident that the use didn't expect or intend. The main reason for these options is that when you're running in bash with `set -e` enabled (and usually you should be for most non-interactive situations) then your script will stop if a process returns an error. So we return an error just in case we did something in a script that a user didn't intend. After all if they think they've successfully invoked a command, but all they've actually done is report the version number or displayed the program help text, they'd probably like to know!

Range Category Meaning
1-9 not much meaning, prefer don't use
10-19 logic error cannot continue now, but nothing is abnormal or wrong
20-39 input error invalid data or inputs
40-59 user error invalid command-line or options
60-79 environment error improper run-time environment
80-89 program error should not happen, unsupported situation
90-99 special purpose success indicators, used for safety
100+ some have meanings in UNIX, otherwise don't use

PHP code

Mostly it's on you as the programmer to pick a suitable error level and exit with it, but a function like this one might help a little bit: 

if ( ! function_exists( 'kickass_exit' ) ) {

  function kickass_exit( $error = 0, $default = 50 ) {

    // 2023-03-31 jj5 - I try to use more or less standard error levels, this is a work in progress
    // but the documentation is here...
    //
    // 2023-03-31 jj5 - SEE: https://www.jj5.net/sixsigma/Error

    if ( is_int( $error ) ) { exit( $error ); }

    if ( is_a( $error, ErrorException::class ) ) { exit( 51 ); }
    if ( is_a( $error, AssertionError::class ) ) { exit( 53 ); }
    if ( is_a( $error, Throwable::class ) ) { exit( 52 ); }

    exit( $default );

  }
}

Unit tests

There is a code allocated for unit test failure, being 54. This constant might be used from shell scripts. In PHP code a unit test will usually fail via an error, exception, or assertion violation, in which case you can just return the appropriate error level, 51, 52, or 53. But if a unit test fails due to a logic situation you can exit with 54 if you want.

BASH code

# 2023-05-26 jj5 - SEE: https://www.jj5.net/sixsigma/Error_levels
#
EXIT_CANNOT_CONTINUE=10 # logic error: cannot continue; but nothing is abnormal or wrong
EXIT_INPUT_ERROR=20     # input error: input error; invalid data or inputs
EXIT_NO_FILE=21         # input error: no file; file/directory path not nominated
EXIT_USER_ERROR=40      # user error: user error; invalid command-line or options
EXIT_WRONG_FILE=41      # user error: wrong file; user nominated file (or directory) missing
EXIT_BAD_FILE=42        # user error: invalid file; user nominated file (or directory) cannot be accessed due to invalid permissions
EXIT_BAD_ENVIRONMENT=60 # environment error: invalid run-time environment; cannot run
EXIT_FILE_MISSING=61    # environment error: file missing; file (or directory) missing
EXIT_NO_ACCESS=62       # environment error: no access; file (or directory) cannot be accessed due to invalid permissions
EXIT_BAD_CONFIG=63      # environment error: invalid configuration; config file missing or invalid
EXIT_NO_SERVICE=76      # environment error: no service; cannot establish connection to service
EXIT_NO_DATABASE=77     # environment error: no database; cannot establish connection to database
EXIT_EXHAUSTED=78       # environment error: resources exhausted; out of memory, disk space, inodes, etc
EXIT_OFFLINE=79         # environment error: system offline; as configured by administrator
EXIT_PROBLEM=80         # program error: software problem; unhandled and fatal situation encountered
EXIT_ERROR=81           # program error: program error; error caused process termination
EXIT_EXCEPTION=82       # program error: program exception; exception caused process termination
EXIT_ASSERT=83          # program error: assertion violation; assertion violation caused process termination
EXIT_TEST_FAILED=84     # program error: test failed; unit-test did not succeed
EXIT_INVALID=89         # program error: invalid error level; the programmer nominated an invalid error level and the host exited with 89 instead
EXIT_SPECIAL_SUCCESS=90 # special purpose: special operation successful; used for safety (in case improperly invoked)
EXIT_OPTIONS_LISTED=98  # special purpose: program options listed; use when programs can be invoked to list their options in a machine readable format
EXIT_HELP=99            # special purpose: help or version number requested
Retrieved from "https://www.jj5.net/wiki/mediawiki/index.php?title=Error_levels&oldid=8330"