ERRORLEVEL

When a batch file runs several commands, you often want to stop if an earlier command fails, or react differently depending on the error.

Command Prompt exposes the result of each command as ERRORLEVEL (the exit code). Using it, you can build error handling into your batch files.

What Is ERRORLEVEL?

ERRORLEVEL is a special value, managed automatically by Command Prompt, that holds the exit code of the most recently executed command. You can read it as %ERRORLEVEL%, just like an environment variable.

How to Check ERRORLEVEL

Method 1: Reference %ERRORLEVEL%

copy "source.txt" "dest.txt"
echo Exit code: %ERRORLEVEL%

Method 2: Test with IF ERRORLEVEL N

copy "source.txt" "dest.txt"
IF ERRORLEVEL 1 (
    echo An error occurred.
)

Method 3: Quick checks with && and ||

copy "source.txt" "dest.txt" && echo Success || echo Failure

Basic Error Handling

Check whether a command succeeded

@echo off
setlocal

copy "important.txt" "backup\important.txt" >nul 2>&1

IF %ERRORLEVEL% EQU 0 (
    echo The copy completed successfully.
) ELSE (
    echo Error: The copy failed. (error code: %ERRORLEVEL%)
)

endlocal

Abort on error

@echo off
setlocal

echo Step 1: Copying the first file...
copy "data.txt" "backup\data.txt" >nul 2>&1
IF %ERRORLEVEL% NEQ 0 (
    echo Error: Step 1 failed.
    GOTO :EOF
)

echo Step 2: Copying the second file...
copy "data2.txt" "backup\data2.txt" >nul 2>&1
IF %ERRORLEVEL% NEQ 0 (
    echo Error: Step 2 failed.
    GOTO :EOF
)

echo All steps completed successfully.
endlocal

Setting a Custom Exit Code

Add a number to EXIT /B to set the exit code of the batch file itself.

@echo off
setlocal

IF NOT EXIST "config.ini" (
    echo Error: Configuration file not found.
    EXIT /B 1
)

IF NOT EXIST "data\" (
    echo Error: Data folder not found.
    EXIT /B 2
)

echo Starting processing.
rem Processing goes here...

echo Processing finished.
EXIT /B 0

The caller can branch on the returned value.

@echo off
call custom_exit.cmd
IF %ERRORLEVEL% EQU 1 echo The configuration file is missing.
IF %ERRORLEVEL% EQU 2 echo The data folder is missing.
IF %ERRORLEVEL% EQU 0 echo Completed successfully.

Exit Codes from Subroutines

A subroutine called with CALL :label can also return an exit code.

@echo off
setlocal

CALL :CHECK_FILE "config.ini"
IF %ERRORLEVEL% NEQ 0 (
    echo Prerequisites are not met. Aborting.
    GOTO :EOF
)

echo Starting processing.
GOTO :EOF

:CHECK_FILE
IF NOT EXIST "%~1" (
    echo Error: %~1 was not found.
    EXIT /B 1
)
echo OK: %~1 was found.
EXIT /B 0

Practical Example: Error Handling with a Log

@echo off
setlocal

rem The format of %DATE% depends on regional settings (yyyy/mm/dd is assumed here)
set LOGFILE=C:\Logs\batch_%DATE:~0,4%%DATE:~5,2%%DATE:~8,2%.log

CALL :LOG "Starting processing."

copy "source\data.csv" "dest\data.csv" >nul 2>&1
IF %ERRORLEVEL% NEQ 0 (
    CALL :LOG "Error: Failed to copy data.csv."
    GOTO END
)
CALL :LOG "Copied data.csv."

copy "source\config.ini" "dest\config.ini" >nul 2>&1
IF %ERRORLEVEL% NEQ 0 (
    CALL :LOG "Error: Failed to copy config.ini."
    GOTO END
)
CALL :LOG "Copied config.ini."

CALL :LOG "All steps completed successfully."

:END
endlocal
GOTO :EOF

:LOG
echo %DATE% %TIME% - %~1
echo %DATE% %TIME% - %~1 >> "%LOGFILE%"
EXIT /B

Pitfalls When Using ERRORLEVEL

Delayed expansion may be needed inside blocks

Inside a parenthesized IF or FOR block, %ERRORLEVEL% is expanded when the block is parsed. To check the result of a command run inside the block, use IF ERRORLEVEL N, or use !ERRORLEVEL! with delayed expansion (see the related article below).

Do not SET ERRORLEVEL yourself

If you assign a value with set ERRORLEVEL=0, %ERRORLEVEL% returns that value instead of the real exit code from then on. To reset the code, run a harmless command such as cmd /c exit /b 0.

Exit code reliability varies by command

Some commands, such as DEL, return 0 even when the file does not exist. For important operations, verify the result directly with IF EXIST.

Exit Codes of Common Commands

Summary

Related Articles

Quiz