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

> Learn how to force recheck torrents in qBittorrent using the GUI, API, or core methods. Quickly verify your torrent data integrity with this essential guide.

- Repository: [qBittorrent project/qBittorrent](https://github.com/qbittorrent/qBittorrent)
- Tags: how-to-guide
- Published: 2026-05-05

---

**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`](https://github.com/qbittorrent/qBittorrent/blob/main/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:

```cpp
// 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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`:

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

```

To recheck multiple torrents, separate hashes with pipe characters:

```bash
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`](https://github.com/qbittorrent/qBittorrent/blob/main/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:

```cpp
// 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:

```cpp
// 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()`:

```cpp
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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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.