How to Force Recheck Torrents in qBittorrent: GUI, API, and Core Implementation Methods

Right-click any torrent in the Transfer List and select "Force recheck," press Ctrl+R, or call the /api/v2/torrents/recheck endpoint with the torrent hash to verify existing data against metadata hashes.

Force rechecking a torrent in qBittorrent triggers a full hash verification of downloaded files against the torrent's metadata. This operation is essential for repairing corrupted data, resolving "missing files" errors, or ensuring seeding integrity. According to the qbittorrent/qBittorrent source code, the force recheck workflow spans three architectural layers: the Qt GUI, the Web UI RPC API, and the underlying BitTorrent session implementation.

Understanding the Force Recheck Workflow

When you initiate a force recheck, qBittorrent instructs the libtorrent engine to compare every piece of existing data against its corresponding hash in the torrent metadata. The process invalidates cached piece maps, updates the torrent state to checking_resume_data, and automatically restarts stopped torrents to perform the verification. Once complete, the torrent resumes its previous state or remains paused depending on configuration.

Method 1: Force Recheck via the GUI Transfer List

Context Menu and Keyboard Shortcuts

The most common method to force recheck torrents is through the Transfer List widget. In src/gui/transferlistwidget.cpp (lines 651-661), the recheckSelectedTorrents() function handles user interactions:

• Right-click one or more selected torrents and choose Force rec&heck
• Keyboard shortcut: Press Ctrl+R with torrents selected

The implementation iterates through the selection and invokes torrent->forceRecheck() for each item:

// From src/gui/transferlistwidget.cpp
void TransferListWidget::recheckSelectedTorrents()
{
    for (BitTorrent::Torrent *const torrent : torrentRows.keys())
        torrent->forceRecheck();
}

Confirmation Dialog Behavior

If the Confirm torrent recheck preference is enabled in settings, the UI displays a confirmation dialog before executing the operation. This safety mechanism is controlled by Preferences::confirmTorrentRecheck() in src/base/preferences.cpp to prevent accidental rechecks on large torrents.

Method 2: Force Recheck via the Web UI and RPC API

API Endpoint and Parameters

Remote clients can trigger rechecks through the Web UI API endpoint defined in src/webui/api/torrentscontroller.cpp (lines 1819-1825). The controller extracts the hash list from the request and invokes the same core method used by the GUI.

Endpoint: POST /api/v2/torrents/recheck

Parameter:

• hashes: Torrent hash or all to recheck every torrent in the session

Example API Request

You can force recheck a specific torrent using curl:

curl -X POST "http://localhost:8080/api/v2/torrents/recheck" \
     -d "hashes=abcdef1234567890abcdef1234567890abcdef12"

To recheck multiple torrents, separate hashes with pipe characters:

curl -X POST "http://localhost:8080/api/v2/torrents/recheck" \
     -d "hashes=hash1|hash2|hash3"

The controller validates each hash, retrieves the corresponding Torrent object, and calls forceRecheck() identically to the GUI path.

Method 3: Core Implementation and libtorrent Integration

Internal Force Recheck Logic

The actual recheck implementation resides in src/base/bittorrent/torrentimpl.cpp (lines 1681-1687) within the TorrentImpl::forceRecheck() method. This function bridges qBittorrent's abstraction layer with the underlying libtorrent library:

// Conceptual implementation from src/base/bittorrent/torrentimpl.cpp
void TorrentImpl::forceRecheck()
{
    if (!hasMetadata()) return;
    
    m_nativeHandle.force_recheck();
    updateCachedStatus();
    clearPieceMaps();
    
    if (isStopped()) {
        start();
        m_stopCondition = StopCondition::FilesChecked;
    }
}

Key Execution Steps

The core implementation performs four critical operations:

1. Metadata validation – Aborts if the torrent lacks metadata (magnet links not yet resolved)
2. libtorrent invocation – Calls m_nativeHandle.force_recheck() to initiate the hash verification pass
3. State synchronization – Updates cached status to checking_resume_data and clears piece-related caches so the UI displays accurate progress
4. Auto-start handling – If the torrent was stopped, the method calls start() and sets the stop condition to FilesChecked, ensuring the torrent pauses automatically after verification completes

Programmatic Usage in Plugins

Developers creating Qt plugins or extensions can trigger rechecks directly through the torrent interface:

// Assuming torrent is a valid BitTorrent::Torrent* pointer
torrent->forceRecheck();

To replicate the Transfer List behavior in custom UI code, connect a QAction to TransferListWidget::recheckSelectedTorrents():

auto *actionForceRecheck = new QAction(
    UIThemeManager::instance()->getIcon(u"force-recheck"_s),
    tr("Force rec&heck"), 
    listMenu
);

connect(actionForceRecheck, &QAction::triggered,
        this, &TransferListWidget::recheckSelectedTorrents);

Configuration Options Affecting Recheck Behavior

Confirmation Preferences

The Confirm torrent recheck setting in Preferences::confirmTorrentRecheck() (defined in src/base/preferences.cpp) controls whether the GUI displays a confirmation dialog. Disabling this allows instant rechecks but increases the risk of accidental triggers.

Automatic Recheck on Completion

When Re-check torrents on completion is enabled via Preferences::recheckTorrentsOnCompletion(), qBittorrent automatically verifies downloaded data immediately after a torrent finishes. This provides an additional integrity layer for critical downloads without manual intervention.

Summary

• GUI method: Select torrents in the Transfer List, right-click > Force recheck, or press Ctrl+R (implemented in src/gui/transferlistwidget.cpp)
• API method: Send a POST request to /api/v2/torrents/recheck with the hashes parameter (handled in src/webui/api/torrentscontroller.cpp)
• Core method: Call torrent->forceRecheck() which executes m_nativeHandle.force_recheck() via libtorrent and handles auto-start for stopped torrents (defined in src/base/bittorrent/torrentimpl.cpp)
• Safety features: Confirmation dialogs respect Preferences::confirmTorrentRecheck(), and automatic recheck on completion is available via Preferences::recheckTorrentsOnCompletion()
• Behavior: Stopped torrents automatically start to perform the check, then pause when finished if they were previously stopped

Frequently Asked Questions

What happens when I force recheck a torrent in qBittorrent?

The client performs a full hash verification of all existing files against the torrent's metadata. It clears cached piece information, sets the status to "Checking," and compares every downloaded piece against its expected hash. If corruption is detected, qBittorrent marks those pieces as missing and re-downloads them during the next active session.

Why is my torrent automatically starting when I force recheck?

According to the implementation in src/base/bittorrent/torrentimpl.cpp, if a torrent is in a stopped state when forceRecheck() is called, the method automatically invokes start() and sets m_stopCondition to FilesChecked. This ensures the recheck can execute (libtorrent requires an active torrent to verify data), then automatically stops the torrent once verification completes.

Can I force recheck multiple torrents at once via the API?

Yes. The /api/v2/torrents/recheck endpoint accepts multiple hashes separated by pipe characters (|) in the hashes parameter, or the special value all to recheck every torrent in the session. The controller iterates through the list and invokes forceRecheck() on each torrent sequentially.

How do I disable the confirmation dialog for rechecking?

Navigate to Tools > Options > Downloads and uncheck Confirm torrent recheck. This preference is stored in Preferences::confirmTorrentRecheck() and removes the confirmation prompt when triggering rechecks from the Transfer List context menu or keyboard shortcut.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}