How to Remove aria2 Control Files on Download Failure

When a download fails or is interrupted in aria2, the utility leaves behind a .aria2 control file to allow for future session resumption. However, if you prefer a clean workspace or want to automate the cleanup of failed downloads, you can configure aria2 to automatically delete these control files using specific command-line flags or configuration settings. This guide explains how to use the --on-download-error hook and script automation to ensure failed downloads don’t leave lingering control files behind.

Understanding the Challenge with aria2 Control Files

By default, aria2 is designed to be highly resilient. The .aria2 control file stores crucial metadata about the download progress, active chunks, and connections. If a download encounters a fatal error (such as a 404 URL error or disk space issues), aria2 stops the process but preserves both the incomplete file and the control file.

While aria2 has a built-in option called --force-save, which determines whether to save a control file even if the download is complete, it does not have a single, direct boolean flag (like --remove-control-file-on-error=true) to delete the control file specifically when a download fails. To achieve this, you must leverage aria2’s event hook system.

The Solution: Using Event Hooks

The cleanest way to automatically remove the control file upon a download failure is to utilize the --on-download-error option. This option allows you to execute an external shell script or command whenever a download finishes with an error.

When aria2 triggers this script, it automatically passes three arguments to it:

  1. GID (The unique Group ID of the download)
  2. Number of files
  3. File path (The path to the first file in the download)

Step 1: Create the Cleanup Script

You can write a simple shell script (or batch file on Windows) that takes the file path passed by aria2, appends the .aria2 extension to target the control file, and deletes it if it exists.

For Linux / macOS (clean-aria2.sh):

#!/bin/bash
# aria2 passes the file path as the 3rd argument ($3)
DOWNLOADED_FILE="$3"
CONTROL_FILE="${DOWNLOADED_FILE}.aria2"

# Check if the control file exists and remove it
if [ -f "$CONTROL_FILE" ]; then
    rm "$CONTROL_FILE"
fi

# Optional: Remove the partial/failed download file as well
if [ -f "$DOWNLOADED_FILE" ]; then
    rm "$DOWNLOADED_FILE"
fi

Make sure to give the script execution permissions: chmod +x clean-aria2.sh

For Windows (clean-aria2.bat):

@echo off
set "DOWNLOADED_FILE=%~3"
set "CONTROL_FILE=%DOWNLOADED_FILE%.aria2"

if exist "%CONTROL_FILE%" del "%CONTROL_FILE%"
if exist "%DOWNLOADED_FILE%" del "%DOWNLOADED_FILE%"

Step 2: Configure aria2 to Use the Script

Once your script is ready, you need to tell aria2 to run it whenever an error occurs. You can do this on a case-by-case basis via the command line, or permanently via your configuration file.

Method A: Command Line Execution Pass the path of your script directly into the aria2c command:

aria2c --on-download-error=/path/to/clean-aria2.sh "URL"

Method B: The aria2.conf Configuration File To make this behavior permanent for all future downloads, add the following line to your aria2.conf file (typically located in ~/.config/aria2/aria2.conf on Linux or the directory where your aria2 executable resides):

on-download-error=/path/to/clean-aria2.sh

By implementation of this event hook, aria2 will immediately invoke your script the moment a download fails, ensuring that both the corrupted partial data and the .aria2 control file are wiped from your storage automatically.