Errorlevel

In Microsoft Windows and MS-DOS, an errorlevel is the integer number returned by a child process when it terminates.

Errorlevel is 0 if the process was successful.

Errorlevel is 1 or greater if the process encountered an error.

Testing errorlevel

Testing errorlevel is useful when you are executing several commands, either at the command line or in a batch file.

Using a conditional expression, you can specify commands to occur only if a previous command was successful. You can also test for failure, executing commands only if the previous command failed. Sometimes, if the program supports it, you can also test for specific types of errors.

You may also branch command execution, so that a different set of commands is executed if the previous command failed.

Conditional "if [not] errorlevel"

The conditional expression "if errorlevel n" is true if the errorlevel is greater than or equal to n.

Similarly, "if not errorlevel n" is true if the errorlevel is less than n.

Let's look at examples of how these can be used, by running some commands on the Windows command line.

To begin, open a command prompt window: press Win + X (hold down the Windows key and press X), and choose Command Prompt.

Now let's run a simple command:

mkdir mydirectory

When we run mkdir (assuming there is not already a directory called "mydirectory" in the current directory), the directory mydirectory is created. The command was successful, so when mkdir terminates, it sets the errorlevel to 0.

Let's test for errorlevel 0.

Testing success: "if not errorlevel"

We can test for errorlevel 0 (success) with the conditional statement if not errorlevel 1. If that's true (errorlevel is less than 1), the command which follows the conditional runs. In the examples below, we'll use the echo command to print a message on the screen.

if not errorlevel 1 echo The last command was successful.

The last command was successful.

As indicated, the mkdir command we ran above was successful.

However, if we try to make the directory again, mkdir fails, because the directory mydirectory already exists:

mkdir mydirectory

A subdirectory or file example already exists.

When mkdir fails, it provides its own error message, "A subdirectory or file example already exists," and sets the errorlevel to 1. If we run our conditional statement again:

if not errorlevel 1 echo The last command was successful.

Nothing happens. Our echo command does not run, because we tested for success — errorlevel less than 1 — and that condition is false.

Testing failure: "if errorlevel"

We can specifically test for failure with if errorlevel 1, which returns true if the errorlevel is 1 or greater.

if errorlevel 1 echo The last command failed.

The last command failed.

The condition is met (because mkdir previously set the errorlevel to 1), and the echo command runs. It would also run if the errorlevel was 2, 3, 4, etc. If the errorlevel was 0, it would not run.

Branching execution with if..else

In the examples above, we tested for success or failure, but not both.

We can test for both success and failure using an if/else statement of the form:

if [not] errorlevel n (command1) else (command2)

For example:

mkdir newtest

if not errorlevel 1 (echo Success) else (echo Failure)

Success

mkdir newtest

A subdirectory or file newtest already exists.

if not errorlevel 1 (echo Success) else (echo Failure)

Failure

%ERRORLEVEL% environment variable

Often, the errorlevel is also stored in the environment variable %ERRORLEVEL%. Its value is a convenient way to access your current errorlevel.

In the following example, we run the dir command twice, once successfully, and once unsuccessfully. After each, we echo the value of %ERRORLEVEL%.

mkdir example

dir example

Directory of C:\Users\Hope\example

06/10/2018  09:43 PM    <DIR>          .
06/10/2018  09:43 PM    <DIR>          ..
               0 File(s)              0 bytes
               2 Dir(s)  50,671,132,672 bytes free

echo %ERRORLEVEL%

0

dir misspelled

Directory of C:\Users\Hope

File Not Found

echo %ERRORLEVEL%

1

Using %ERRORLEVEL% in conditionals

You can use %ERRORLEVEL% in conditionals, for example:

if %ERRORLEVEL% NEQ 0 echo Errorlevel is not equal to zero, the last command failed.

Note: %ERRORLEVEL% is not always correct

%ERRORLEVEL% is not the same as if [not] errorlevel, and the two values are not always the same. Specifically, %ERRORLEVEL% does not always get updated when the errorlevel changes. For more information, see this MSDN blog post by Raymond Chen.

For this reason, if you are testing errorlevel in a production environment, it's better to use if [not] errorlevel.

Errorlevel lookup tool

For advanced users and software developers, Microsoft has released a command-line errorlevel lookup tool, err.exe. It lets you search for errorlevels by number or internal name, and restrict your search by the header file where the errorlevel is defined.

err /winerror.h 0

# winerror.h selected.
# for hex 0x0 / decimal 0 :
  ERROR_SUCCESS                                                 winerror.h
# The operation completed successfully.
  NO_ERROR                                                      winerror.h
  SEC_E_OK                                                      winerror.h
  S_OK                                                          winerror.h
# 4 matches found for "0"

err /cmdmsg.h 9009

# cmdmsg.h selected.
# for decimal 9009 / hex 0x2331 :
  MSG_DIR_BAD_COMMAND_OR_FILE                                   cmdmsg.h
# '%1' is not recognized as an internal or external command,
# operable program or batch file.
# 1 matches found for "9009"

Programming terms