What are the ERRORLEVEL values set by internal cmd.exe commands?

Question

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)?

Deice

Answer 1

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

BREAK
ECHO
ENDLOCAL
FOR      Not change the ERRORLEVEL by itself. See "Exit Code" below.
IF       Not change the ERRORLEVEL by itself.
PAUSE
RD       Not change the ERRORLEVEL on errors, but the "Exit Code". See below.
REM
RMDIR    Same as RD.
SET      Plain SET command (no arguments). See "Table 3" below.
TITLE

Table 2 - Commands that set ERRORLEVEL to 0 or 1 depending on result

Command │ Set ERRORLEVEL = 0 when       │ Set ERRORLEVEL = 1 when
────────┼───────────────────────────────┼─────────────────────────────────────────────────────────────
CD      │Current directory was changed. │Directory not exists or is not accessible.
CHDIR   │Same as CD.                    │
COLOR   │Color was changed.             │Background and foreground colors are the same.
COPY    │File(s) was processed.         │File not found or bad parameters given.
DATE    │Date was changed or not given. │User has no admin privileges.
DEL     │Almost always, excepting when: │Bad or no parameters given.
DIR     │Same as COPY.                  │
ERASE   │Same as DEL.                   │
MD      │Directory was created.         │Directory could not be created.
MKDIR   │Same as MD.                    │
MKLINK  │Link was created.              │Link could not be created or bad parameters given.
MOVE    │File(s) was moved/renamed.     │File not found, could not be moved/renamed or bad parameters.
PUSHD   │Same as CD.                    │+ Bad switch given.
REN     │Same as MOVE.                  │
RENAME  │Same as MOVE.                  │
SETLOCAL│New environment was created.   │Bad parameters given.
TIME    │Time was changed or not given. │User has no admin privileges.
TYPE    │Same as COPY.                  │
VERIFY  │Right or no parameters given.  │Bad parameters given.
VOL     │Volume label was displayed.    │Drive not found or bad parameters given.

VERIFY is the command suggested by MS to set the ERRORLEVEL to 0 or 1; see the example in SETLOCAL /?.

Table 3 - Commands that set the ERRORLEVEL on error; otherwise, not change it

Command      │E│ Set ERRORLEVEL to = when
─────────────┼─┼────────────────────────────────────────────────────────────────────────
ASSOC        │*│1 = Extension associations could not be changed.
CLS          │ │1 = Bad switch given.
DPATH        │*│1 = Data path could not be established.
FTYPE        │*│1 = File type associations could not be changed.
GOTO label   │ │1 = Label not exist *in a subroutine* (equivalent to: EXIT /B 1).
KEYS         │ │1 = Bad switch given.
PATH         │*│1 = Path could not be changed.
POPD         │ │1 = Bad switch given.
PROMPT       |*│1 = Prompt could not be changed.
SET var      │*│1 = No variable with such name exists.
SET var=value│*│1 = Variable name start with "/" not enclosed in quotes.
SET /P       │*│1 = Read an empty line or at end of file.
SET /A       │*│1073750988 = Unbalanced parentheses, 1073750989 = Missing operand, 
             │ │1073750990 = Syntax error, 1073750991 = Invalid number,
             │ │1073750992 = Number larger than 32-bits, 1073750993 = Division by zero.
SHIFT        │ │1 = Bad switch given.

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

CALL Table1     │If the called command is anyone of Table 1 (excepting FOR and IF): set ERRORLEVEL = 0.
CALL subroutine │If the subroutine is called, not change prior ERRORLEVEL value;
                │otherwise (subroutine not exists): set ERRORLEVEL = 1.
EXIT /B, EXIT   │Not change prior ERRORLEVEL value.
EXIT /B number  │Set ERRORLEVEL to given number.
EXIT number     │Ends cmd.exe and set its returning ERRORLEVEL value to given number.
START command   │If command is started, not change ERRORLEVEL; otherwise, set ERRORLEVEL = 9059.
START /WAIT bat |When the started Batch file ends, set ERRORLEVEL = value from 'EXIT number' commmand.
notExist        │If a non-existent command is entered for execution, set ERRORLEVEL = 9009.
VER             │Set ERRORLEVEL = 0 almost always. If /? parameter is given, not change ERRORLEVEL.

Exit Code management

There are two ways to test the ERRORLEVEL value: via IF ERRORLEVEL / IF %ERRORLEVEL% command, or using the command && 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 the elseCmd part. You may read further details on this matter at this post.

Table 5 - Commands or features that set the Exit Code

Feature      │ Set Exit Code to = when
─────────────┼─────────────────────────────────────────────────────────────────────────
command      │1 = Command not exist (when ERRORLEVEL = 9009).
redirection  │1 = File not exists in "<", path not exists or access denied in ">" ">>".
drive:       |1 = Drive unit not exists.
POPD         |1 = No matching PUSHD was previously executed.
RD           │1 = Bad switch given, 2 = Directory not found, 5 = Access denied,
             │32 = Directory in use, 145 = Directory not empty.
FOR /F       │1 = No data was processed.

For example, to test if a redirection error happened, use this:

command > C:\Path\that\does\not\exist\file.txt || rem
if errorlevel 1 echo Previous redirection failed

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 (excepting FOR and IF).

To test if a drive unit exists:

U: || rem
if errorlevel 1 echo Previous set current drive to U: unit failed

More examples:

rd c:\Some\directory 2> NUL || rem
if %errorlevel% equ 0 (
   echo Directory deleted
) else if %errorlevel% equ 2 (
   echo Directory not found
) else if %errorlevel% equ 5 (
   echo Can not access the directory, check rights
) else if %errorlevel% equ 32 (
   echo Can not delete current directory
) else if %errorlevel% equ 145 (
   echo Directory is not empty, use /S switch
)


(for /F "options" %%a in (input.txt) do echo %%a) || rem
if errorlevel 1 echo Previous FOR didn't processed any value

Deice

I could have sworn it wasn't there when I checked. Perhaps you had multiple rapid succession edits. There are so many things to test, I suspect it may take a long time before this answer is complete. Ideally, every option of every command should be tested with invalid values, both with and without ||. I find it odd that some commands produce non-zero values other than 1, but most produce 1. I suspect additional commands might be able to yield something other than 0 or 1. Certainly there are additional unlisted conditions that can at least lead to ERRORLEVEL 1. – Summerwood

@dbenham: Well, these tables are definitely useful even if they does not include all possible error situations of all existent commands (BTW a small example, a simple way to check for admin privileges: date %date%). Anyway, the new data may be added as they be discovered, but I really doubt that any normal Batch file user may require a value not already listed here... – Deice

@jeb: I really want not to include non-standard mechanisms that require an additional explanation and that certainly will not be used by the vast majority of users. I added goto labelNotExist to Table 3. – Deice

EXIT and EXIT number do not return an ERRORLEVEL, but rather return a process exit code. If the terminating cmd session was itself launched by a parent cmd.exe session, then the parent session will handle the exit code as with any external command - it will transfer the exit code value to the parent's ERRORLEVEL. – Summerwood

@Deice I agree, I removed my last comment. But goto unknownLabel only sets the errorlevel when it's used with || else the batch exits and the errorlevel will be unchanged – Cassity

as the bad switches are different kind of syntax error here's resume of the internal commands that take the bad switches into account - pastebin.com/2t2QsjRB – Thoughtless

@dbenham: I think this is precisely what I said in Table 4: "EXIT number │Ends cmd.exe and set its returning ERRORLEVEL value to given number". Do you think is not clear enough? IMO a further explanation at this point would be confusing instead of useful. – Deice

@jeb: Err, no. goto unknowLabel is similar to exit /B 1 when it is executed in a subroutine. The behavior you describe happens only when the goto unknowLabel is executed in the main file (the original Batch file executed from command prompt). However, goto unknowLabel in a subroutine does not "break" an iterative for in the same way goto label or exit /B 1 does: the cycle continue until last value and at that point an exit /B is executed. – Deice

@npocmaka: Yes, the bad switch error is reported as a standard error in several commands (BTW interesting table! I will review it and change the data here as needed). The only internal command that report a bad switch error differently than other errors is RD via the Exit Code. – Deice

Umm, no, what you said about EXIT does not precisely agree with my comment, which you half acknowledge with your statement that more explanation would be confusing. I agree it is confusing, but I also think it is important, else I wouldn't have written the comment. – Summerwood

@dbenham: The value set by EXIT number command is always converted into an ERRORLEVEL when such command is used in a Batch file (that is the purpose of this question as originally stated). From this point of view, EXIT number command does set the ERRORLEVEL and such value may be used in a posterior if ERRORLEVEL one, so no further explanations are needed. Am I wrong? The purpose of these tables is to provide reference information useful to Batch file programmers, not to discuss every possible aspect of these commands. – Deice

255 when The process tried to write to a nonexistent pipe. . To emulate this you need a batch with serious syntax error in for,if or invalid expansion. Try with test bat file like rem %~ and then test.bat|rem and then print the errorlevel. – Thoughtless

@npocmaka: This is strange. Yes, your example show an errorlevel of 255, but such a value does not come from the "nonexistent pipe" error. Try: (pause>CON & echo No pipe) | rem that show the same error, but with an errorlevel of zero... – Deice

@npocmaka: Indeed, a Batch file with @echo off and rem %~ does not show the "nonexistent pipe" error, but DO return an errorlevel of 255 when executed as you said: test.bat|rem. This may mean that 255 indicate that the process at left side of the pipe have a certain type of error... – Deice

@Deice - you are right. The parsing errors produces 255. I've called the bat through powershell to see the errorlevel. things like if a a a , for /f a a a and the %~ returned 255. – Thoughtless

btw. some command behavior is different with command extensions disabled. – Thoughtless

@npocmaka: The commands that change its behaviour with Extensions disabled are specifically mentioned in Table 3. Do you mean another command, different than these ones? – Deice

rd,del,cd,pushd set error level to 1 when not existing network path is passed . Probably some external function is called. – Thoughtless

start "" /d "c:\notExistingDir" notepad sets errorlevel to 9084 . There are few more cases when start has exit code 1 and errorlevel 0 – Thoughtless

Remember that ERRORLEVEL functionality has varied by OS version! In Windows NT 4, plain SET would reset ERRORLEVEL to 0. Also, related resources: Errorlevels - how to check for and set errorlevels, Dynamic Environment Variables - ExitCode variables, why you should Never Set Errorlevel, and Raymond Chen's blog on ERRORLEVEL is not %ERRORLEVEL%. – Hoodwink

@GlennFromIowa: Mmmm... The purpose of this answer is not to teach about ERRORLEVEL details, but just to show the values set by internal commands. The linked pages are pretty outdated. Yes, you should never set the ERRORLEVEL variable, but the exact same point apply to CD, DATE, TIME and RANDOM dynamic variables... – Deice

@Deice Mmmm... And yet, you have a section and examples in the answer on Exit Code Management. Besides, the main point and first sentence in my comment was that ERRORLEVEL can be version dependent. And while a list of ERRORLEVEL values is helpful, trapping errors is so much more complex. For example, see this post, where it's suggested that %ERRORLEVEL% is not the most reliable way to trap errors! I left a comment below this great answer to point people just learning about error trapping in batch files to some helpful resources. – Hoodwink

@GlennFromIowa: ERRORLEVEL functionality is not version dependent. If plain SET command really set the errorlevel to a value "(usually 0)", then it is a particular case of "Windows NT 4 (and 2000?)". Perhaps a small note about this point at end of Table 3 be enough, but I could not find a reliable source that may confirm this behavior (Rob van der Woude's pages are not reliable)... I already included a link to such "great answer" at end of Exit Code management section, in the phrase: "You may read further details on this matter at this post". – Deice

echo(>&1||rem sets errorlevel to 1 and prints this message The handle could not be duplicated during redirection of handle 1. – Thoughtless

Using cmd (hence opening a new Command Prompt instance) resets the ErrorLevel, so the new instance begins with a value of 0, and when exit, ErrorLevel is reset too… – Monosome

What I do not quite get is the column "E" in Table 3; are you talking about the "Command Extensions"? I mean, the commands DPATH, PATH, PROMPT, SET reset ErrorLevel to 0 only in .cmd file context, independent on whether or not Command Extensions are enabled (and ASSOC, FTYPE, SET /A and SET /P are anyway not available with Command Extensions disabled). Or do I misunderstand your point? – Monosome