Read Unrar Error Codes in a Bash Script

Automating archive extraction often requires handling failures programmatically, such as identifying corrupt archives, missing files, or incorrect passwords. When the unrar utility finishes execution, it returns a numeric exit code to the shell representing the outcome of the operation. In a Bash script, you can read this error code by querying the $? variable immediately after running the command, allowing your script to route execution depending on whether the process succeeded, failed due to bad integrity, or encountered missing files.

Capturing the Exit Code

In Bash, the special parameter $? stores the exit status of the most recently executed foreground pipeline. Because subsequent commands (even a simple echo) overwrite this variable, you must store it into a designated variable immediately following the unrar command.

unrar x -y archive.rar /destination/path/
UNRAR_EXIT_CODE=$?

Unrar Exit Codes Reference

The unrar utility uses standard predefined status codes:

  • 0 (SUCCESS): Successful operation.
  • 1 (WARNING): Non-fatal error (such as files already existing or skipped).
  • 2 (FATAL_ERROR): A fatal error occurred (e.g., unexpected format or generic failure).
  • 3 (CRC_ERROR): A CRC error occurred (corrupted data or incorrect decryption password).
  • 4 (LOCK_ERROR): Attempt was made to modify a locked archive.
  • 5 (WRITE_ERROR): Disk write error (e.g., insufficient disk space or permission denied).
  • 6 (OPEN_ERROR): File open error (archive file not found or inaccessible).
  • 7 (USER_ERROR): Command-line option or syntax error.
  • 8 (MEMORY_ERROR): Insufficient memory to complete the operation.
  • 9 (CREATE_ERROR): File create error.
  • 255 (USER_BREAK): Process interrupted or canceled by the user.

Implementation Example

The most robust way to evaluate multiple specific exit codes in Bash is with a case statement. The following script extracts an archive and executes specific logic depending on the code returned:

#!/usr/bin/env bash

ARCHIVE="data.rar"
TARGET_DIR="./extracted/"

# Run unrar in silent/assume-yes mode
unrar x -inul -y "$ARCHIVE" "$TARGET_DIR"
EXIT_CODE=$?

case $EXIT_CODE in
    0)
        echo "Extraction completed successfully."
        ;;
    1)
        echo "Warning: Non-fatal errors encountered."
        ;;
    2)
        echo "Fatal error: Archive might be severely damaged."
        ;;
    3)
        echo "Data error: CRC mismatch or incorrect password."
        ;;
    5)
        echo "Write error: Verify disk space and write permissions."
        ;;
    6)
        echo "Open error: Could not find or open '$ARCHIVE'."
        ;;
    7)
        echo "User error: Check your unrar command syntax."
        ;;
    8)
        echo "Memory error: Not enough memory to complete extraction."
        ;;
    *)
        echo "Extraction failed with unknown error code: $EXIT_CODE"
        exit $EXIT_CODE
        ;;
esac

Capturing and evaluating $? directly provides clean error handling without relying on brittle text scraping from standard error streams.