How to Use IF ERRORLEVEL to Check Exit Codes in Batch Script

One of the most critical features for writing robust, intelligent batch scripts is the ability to check whether a command succeeded or failed. Did that COPY command actually work? Did the backup utility encounter an error? This is accomplished by checking the exit code, a special numerical value that every command-line program returns when it finishes.

This guide will teach you how to check these exit codes using the classic IF ERRORLEVEL statement. You will learn the single most important rule about how it works ("greater than or equal to"), the correct way to check for both success and failure, and the modern alternative (%ERRORLEVEL%) that is often easier to read.

What is an Exit Code? (The ERRORLEVEL)

When any command-line program finishes, it returns a number to the operating system called an exit code. This code is a signal of its final status. By convention:

• Exit Code 0: The command completed successfully.
• Non-Zero Exit Code (1, 2, 5, etc.): The command failed or encountered an error.

The command processor stores this value in a special, dynamic variable called ERRORLEVEL. Your script can check this value immediately after a command runs to determine what to do next.

The Core Command: IF ERRORLEVEL N

The IF ERRORLEVEL statement is the traditional way to check this value. It allows you to execute another command conditionally based on the exit code.

Syntax: IF ERRORLEVEL [Number] (command)

The Critical Rule: "Greater Than or Equal To"

This is the most important and most misunderstood part of this command. The statement IF ERRORLEVEL N does not mean "if the error level is exactly N."

It means: "If the error level is N or greater."

• IF ERRORLEVEL 1: This is TRUE for exit codes 1, 2, 5, 100, etc.
• IF ERRORLEVEL 5: This is TRUE for exit codes 5, 6, 10, etc., but FALSE for 4.

Understanding this rule is the key to using IF ERRORLEVEL correctly.

The Correct Way to Check for Success (Exit Code 0)

A common mistake for beginners is to write IF ERRORLEVEL 0 to check for success. This is a logical flaw, because every exit code is 0 or greater, so this condition will always be true.

The correct, classic method is to check if the error level is not 1 or greater.

Syntax for Success: IF NOT ERRORLEVEL 1 (command)

This correctly isolates the exit code 0 as the only success condition.

Example of script:

@ECHO OFF
REM The DIR command on an existing file returns ERRORLEVEL 0.
DIR C:\Windows\System32\kernel32.dll > NUL

IF NOT ERRORLEVEL 1 (
    ECHO [SUCCESS] The command completed successfully.
) ELSE (
    ECHO [FAILURE] The command failed.
)

The Correct Way to Check for Failure (Any Non-Zero Exit Code)

Based on the "greater than or equal to" rule, checking for failure is very straightforward. Since all failure codes are 1 or higher, this is the perfect check.

Syntax for Failure: IF ERRORLEVEL 1 (command)

Example of script:

@ECHO OFF
REM The DIR command on a non-existent file returns ERRORLEVEL 1.
DIR non_existent_file.txt > NUL 2> NUL

IF ERRORLEVEL 1 (
    ECHO [FAILURE] The command failed as expected.
) ELSE (
    ECHO [SUCCESS] The command succeeded.
)

The Modern Alternative: Comparing %ERRORLEVEL% Directly

The IF ERRORLEVEL N syntax, while traditional, can be confusing. Modern batch scripting has a dynamic variable, %ERRORLEVEL%, which holds the exact value of the last exit code. This allows for much more intuitive and precise comparisons.

• To check for success: IF %ERRORLEVEL% EQU 0
• To check for failure: IF %ERRORLEVEL% NEQ 0
• To check for a specific error code: IF %ERRORLEVEL% EQU 5

EQU means "Equal To," and NEQ means "Not Equal To."

Example of script (using the modern syntax):

@ECHO OFF
DIR non_existent_file.txt > NUL 2> NUL

IF %ERRORLEVEL% EQU 0 (
    ECHO [SUCCESS] The command succeeded.
) ELSE (
    ECHO [FAILURE] The command failed with exit code: %ERRORLEVEL%
)

note

For new scripts, this method is highly recommended for its clarity and precision.

Common Pitfalls and How to Solve Them

• Incorrect Success Check: Using IF ERRORLEVEL 0. Always use IF NOT ERRORLEVEL 1 or IF %ERRORLEVEL% EQU 0.
• Order of Checks: If you need to check for multiple specific error codes, you must check from highest to lowest when using the classic syntax.

  REM CORRECT ORDER
  IF ERRORLEVEL 5 ECHO Code was 5 or greater.
  IF ERRORLEVEL 2 ECHO Code was 2, 3, or 4.
  IF ERRORLEVEL 1 ECHO Code was 1.

  This is because the "greater than or equal to" logic would cause an IF ERRORLEVEL 1 to trigger for an exit code of 5, stopping the check prematurely if it came first. The modern %ERRORLEVEL% EQU N syntax does not have this problem.

Practical Example: A Robocopy Backup Script

Robocopy is a great example because it returns multiple success codes. Any code less than 8 indicates success.

@ECHO OFF
SET "SOURCE=C:\MyData"
SET "DEST=D:\Backup"

ROBOCOPY "%SOURCE%" "%DEST%" /E > NUL

REM --- Classic Check ---
REM Check if the exit code is 8 or greater (a failure).
IF ERRORLEVEL 8 (
    ECHO [FAILURE] Robocopy reported a serious error.
) ELSE (
    ECHO [SUCCESS] Robocopy backup completed without fatal errors.
)

REM --- Modern Check (more readable) ---
IF %ERRORLEVEL% LSS 8 (
    ECHO [SUCCESS] Robocopy backup completed without fatal errors.
) ELSE (
    ECHO [FAILURE] Robocopy reported a serious error. Code: %ERRORLEVEL%
)

Conclusion

Checking the exit code of commands is the key to writing scripts that are robust, can react to failure, and can be trusted in an automated environment.

• The classic IF ERRORLEVEL N syntax means "if the exit code is N or greater." It is essential to know, especially for reading older scripts.
  • Success check: IF NOT ERRORLEVEL 1
  • Failure check: IF ERRORLEVEL 1
• The modern %ERRORLEVEL% EQU N syntax is recommended for new scripts. It is more intuitive, less prone to logical errors, and allows for checking exact error codes.

Adopting the habit of checking ERRORLEVEL after every critical command will elevate the quality and reliability of your batch scripts.