# Failure Clusters

Source: https://docs.qualflare.com/docs/ai/failure-clusters · Last updated: 2026-10-27

Qualflare groups similar failures from uploaded launches into failure clusters, labels each at 5 failures and opens a defect. Review, merge and export them.

In Qualflare, a [**failure cluster**](https://docs.qualflare.com/docs/reference/glossary#failure-cluster) is a group of failed test results that share a root cause; Qualflare groups the failures of every launch you upload and names a cluster once it holds 5 failures.

| Fact     | Detail                                                                                                                                                                                                                                                                                        |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where    | **Failure Clusters** under **Analysis** in the project sidebar                                                                                                                                                                                                                                |
| Plans    | (available on Starter, Core, Scale, Enterprise). Starter holds 2 failure clusters at a time across the workspace                                                                                                                                                                              |
| Requires | **Enable AI Features** on in the project ([Project AI settings](https://docs.qualflare.com/docs/ai/limits#project-ai-settings))                                                                                                                                                               |
| Who      | View: (requires the Viewer role or higher in the project). Rename, merge, recalculate and delete: (requires the Editor role or higher in the project), except **Delete** on a cluster's page ([Delete clusters](https://docs.qualflare.com/docs/ai/failure-clusters#deleting-clusters)) |
| CLI      | `qf <identifier> clusters list` and `qf <identifier> cluster get <id>` ([Clusters commands](https://docs.qualflare.com/docs/cli/read-commands#clusters))                                                                                                                                      |
| MCP      | `list_failure_clusters` and `get_failure_cluster` ([MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference))                                                                                                                                                                 |

## How failure clustering works

Qualflare builds failure clusters in the background, after each upload:

1. Only launches you upload, and only those with failures, are clustered. Launches you start in the app ([manual runs](https://docs.qualflare.com/docs/runs/manual-testing)) are not.
2. Each failure (its suite, case and error text) joins the most similar cluster at 85% similarity or more. Between 50% and 85% it joins pending a check that can move it to a new cluster: from 80% it is confirmed without a model call, under 55% it is moved without one, and in between an AI check decides. Under 50% it starts a new cluster.
3. A cluster stays **Pending** until it holds 5 failures. Then Qualflare names it and adds a summary, a severity (Medium when none is given), a root cause and a fix suggestion, and the status becomes **Analysed**.
4. At that moment Qualflare creates the cluster's defect, or reopens its closed one, and notifies the project's members (`New defect created: <label>`). The **Cluster Notifications** email and the Cluster Created event for your [integrations](https://docs.qualflare.com/docs/integrations) follow, once per cluster. See [How defects are created](https://docs.qualflare.com/docs/defects#how-defects-are-created). Cluster Created isn't a webhook event: [webhooks](https://docs.qualflare.com/docs/integrations/webhooks) send `launch.completed` and `defect.created`.
5. When new failures join a named cluster whose defect is **Closed**, Qualflare reopens the defect as a regression, with the reason `Regression detected. Previous defect #<n> closed on <date>. New failures in cluster.`, and notifies the project (`Regression detected: <label>`). A defect marked **False positive** stays closed.
6. When the workspace holds its plan's number of clusters, failures with a new pattern are still saved with their results, but they are not grouped.

*Figure: The Failure Clusters list, with the 30-day Cluster Trend chart above it.*

## The Failure Clusters list

The Failure Clusters list shows the project's clusters with the columns **Label** (with the summary under it), **Severity**, **Status**, **Failures**, **First Seen** and **Last Seen**. You can sort by Label, Failures, First Seen and Last Seen, and filter by **Severity**, **Status** and **Search**. Above the list, the **Cluster Trend** chart covers the last 30 days (**Failures Collected** and **Total Clusters**). To download the clusters, see [Export clusters](https://docs.qualflare.com/docs/ai/failure-clusters#exporting-clusters).

* **Severity:** Critical, High, Medium or Low.
* **Status:** **Pending** means the cluster has fewer than 5 failures and has not been named yet; a small cluster can stay Pending. **Analysed** means Qualflare has named and analysed it.

## Review a cluster

To review a failure cluster, click it in the list. Its page shows the label, severity, status and when it was created, with two tabs.

### Overview tab

The **Overview** tab shows the **Root Cause** and the **Fix Suggestion**. A Pending cluster shows "This cluster is still being analysed…" instead, which means it has fewer than 5 failures.

*Figure: Once a cluster holds 5 failures, its Overview tab shows the root cause and a fix suggestion.*

### Sample Failures tab

The **Sample Failures** tab lists a sample of the cluster's failures, each with its case, suite, error and a `<n>% match` that shows how closely it matches the cluster.

*Figure: Each sample failure shows how closely it matches the cluster.*

The cluster's defect is in **Defects**, and its panel links back to the cluster in a Linked Cluster card ([Create, triage and close defects](https://docs.qualflare.com/docs/defects/manage-defects)).

## Rename a cluster

To rename a failure cluster, choose More options (⋯) › **Rename** on its row or on the cluster's page, then enter the new label. Renaming needs (requires the Editor role or higher in the project).

*Figure: Rename, recalculate or delete one cluster from its row menu.*

## Merge clusters

> **Caution: Merging can't be undone**
>
> Merging deletes every selected cluster except the target. Their failures move to the target.

To merge failure clusters that describe the same issue, keep one as the target:

1. Tick two or more clusters in the list. **Merge** appears in the bulk bar only with 2 or more selected, and the bulk bar needs (requires the Editor role or higher in the project).

   *Figure: Merge appears in the bulk bar once you select two or more clusters.*

2. Click **Merge** in the bulk bar. The **Merge Clusters** dialog opens.

3. Choose the cluster to keep as the target.

   *Figure: Choose the cluster to keep; the other selected clusters are merged into it and deleted.*

4. Click **Merge Clusters**. You should see one cluster with the failure counts added together.

**Change Status** and **Archive** in the bulk bar don't change clusters; they only show `Change status coming soon` and `Archive coming soon`.

## Recalculate a cluster

To recalculate a failure cluster, choose **Recalculate Centroid** from its ⋯ menu in the list (**Recalculate** on the cluster's page). Qualflare recomputes the cluster's reference pattern and failure count from the failures it holds now, which changes how future failures match it. It doesn't move failures that are already grouped. To combine clusters that describe the same issue, merge them. Recalculating needs (requires the Editor role or higher in the project).

## Delete clusters

> **Caution: Deleting a cluster can't be undone**
>
> Its label, analysis and grouping can't be recovered.

To delete failure clusters, select one or more in the list and click **Delete**, or choose **Delete** from a row's menu or the cluster's page, then confirm.

On the cluster's page, **Delete** needs (requires the Owner role in the project); in the list and the API, deleting needs (requires the Editor role or higher in the project).

## Export clusters

To export failure clusters, click **Export CSV** on the list page. It downloads every cluster in the project.

## Cluster fields and actions

Every failure cluster has these fields and actions.

### Cluster fields

| Field          | Description                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Label          | AI-generated name for the failure pattern                                                           |
| Summary        | Brief description of the cluster                                                                    |
| Severity       | Critical / High / Medium / Low                                                                      |
| Status         | Pending (fewer than 5 failures, not named yet) / Analysed (named; a defect was created or reopened) |
| Failures       | Number of test failures in this cluster                                                             |
| Root Cause     | AI-analyzed explanation of why failures occur (Analysed only)                                       |
| Fix Suggestion | AI-recommended remediation (Analysed only)                                                          |
| First Seen     | Date the pattern was first detected                                                                 |
| Last Seen      | Most recent detection date                                                                          |

### Cluster actions

| Action                             | Where                         | Role                                                                                | Effect                                                                               |
| ---------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Rename                             | Row ⋯, cluster page           | (requires the Editor role or higher in the project)                                 | Changes the label                                                                    |
| Merge                              | Bulk bar (2+ selected)        | (requires the Editor role or higher in the project)                                 | Moves the failures to the target and **deletes the other clusters**; can't be undone |
| Recalculate Centroid / Recalculate | Row ⋯ / cluster page          | (requires the Editor role or higher in the project)                                 | Recomputes the pattern and count; moves no failures                                  |
| Delete                             | Row ⋯, bulk bar, cluster page | Editor+; on the cluster page the app needs (requires the Owner role in the project) | Deletes the cluster; can't be undone                                                 |
| Export CSV                         | List page                     | (requires the Viewer role or higher in the project)                                 | Downloads every cluster                                                              |

## Limits and plan availability

Failure clustering (available on Starter, Core, Scale, Enterprise) limits the clusters a workspace holds at once: Starter 2, Core Unlimited, Scale Unlimited, Enterprise Unlimited. The Open Source plan doesn't include clustering.

If you see a feature lock, your workspace is not entitled to failure clustering, for example on the Open Source plan. Turning project AI off stops clustering for new launches. See [AI usage limits](https://docs.qualflare.com/docs/ai/limits#failure-clusters).

## Related

* **Guides:** [AI Launch Analysis](https://docs.qualflare.com/docs/ai/launch-analysis) · [Create, triage and close defects](https://docs.qualflare.com/docs/defects/manage-defects) · [Analyze launch results](https://docs.qualflare.com/docs/runs/analyze-results)
* **Reference:** [Defects](https://docs.qualflare.com/docs/defects) · [AI Features settings and limits](https://docs.qualflare.com/docs/ai/limits) · [Glossary: Failure cluster](https://docs.qualflare.com/docs/reference/glossary#failure-cluster)
* **CLI/API:** [Clusters commands](https://docs.qualflare.com/docs/cli/read-commands#clusters) · [MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)