The ERRORLEVEL is a value returned by most cmd.exe commands when they end that change depending on a series of conditions, so knowing the value that the commands return is valuable information that may aid to write better Batch files. All external .exe programs change the ERRORLEVEL when they end (that is an inherent mechanism of both ExitProcess and TerminateProcess Win-32 API functions) and usually such values are documented, but the values returned by internal cmd.exe commands are not fully documented elsewhere.
A table with partial ERRORLEVEL values appears at this question, but just for internal commands that set ERRORLEVEL=0 "upon success". I suggested the OP of such question to modify it in order to also include the values returned by "not successful commands", but he refused and invited me to post my own question/answer, so here it is! You must note that an ERRORLEVEL different than zero does not necessarily means that the command failed! There are some commands that end with no error and return a value greater than zero to indicate different "exit status", including internal commands (like SET /P
).
To make better use of the built-in cmd.exe commands in Batch .bat files we need to know the ERRORLEVEL values they return and the mechanisms involved in this management. So the question is, which internal cmd.exe commands set the ERRORLEVEL to any value (including zero)?
Best Answer
In this answer the ERRORLEVEL values returned by all internal cmd.exe commands are described; they are grouped by the way the value is changed and presented as quick reference tables. I reviewed other similar tables in order to assemble this one, but filled the missing values via tests performed in a Windows 8.1 computer. I made my best effort to create these tables complete and precise, but I had not tested each and everyone of the values reported here, so it may be subtle inconsistencies.
Table 1 - Commands that not change the prior ERRORLEVEL value
Table 2 - Commands that set ERRORLEVEL to 0 or 1 depending on result
Table 3 - Commands that set the ERRORLEVEL on error; otherwise, not change it
The "E" column in Table 3 indicate those commands that change their behavior accordingly to the "Extensions" status as described in the corresponding documentation. When Extensions are enabled (the default) and these commands are placed in a file with
.CMD
extension instead of.BAT
one, these commands set SETERRORLEVEL = 0 when they ends with no error, that is, when the conditions described in Table 3 are not present.Table 4 - Special cases
Exit Code management
There are two ways to test the ERRORLEVEL value: via
IF ERRORLEVEL / IF %ERRORLEVEL%
command, or using thecommand && thenCmd when ERRORLEVEL is 0 || elseCmd when ERRORLEVEL is not 0
construct. However, certain particular commands and redirection errors returns a value that only works in the second case and is not reflected in the ERRORLEVEL; we may call "Exit Code" this value. When this Exit Code is not zero, it can be passed to the ERRORLEVEL executing any command of Table 1 in theelseCmd
part. You may read further details on this matter at this post.Table 5 - Commands or features that set the Exit Code
For example, to test if a redirection error happened, use this:
In this example the
rem
command is used to copy the Exit Code to the ERRORLEVEL, but any other internal command that preserve the ERRORLEVEL may be used (exceptingFOR
andIF
).To test if a drive unit exists:
More examples: