> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Issues and error grouping

> Learn which errors become issues, how Squasher groups them, and how to change an issue's status, priority, owner, and duplicates.

An issue is one group of matching errors in a project. Squasher adds each new
matching error to the same issue. The issue keeps a count of events and the
times the error was first seen and last seen.

<Note>
  The dashboard calls these records **Issues**. The API paths stay under `/errors`, and the CLI
  command stays `squasher errors`. See the [Error groups API](/api-reference/errors).
</Note>

## What creates an issue

Squasher creates or updates an issue from these signals:

* **SDK errors.** Squasher SDK events are error-level unless the event sets a
  lower level. Events from a [Sentry SDK](/integrations/sentry) sent to Squasher
  use the same rule.
* **Error-level logs.** A log record becomes an issue event when its severity
  number is 17 or higher, or its severity text is `error` or `fatal` in any case. This
  applies to OpenTelemetry logs and to logs from [log drains](/integrations/logging-overview).
* **Error spans.** A span with status `ERROR` becomes an issue event. The
  message is the span status message. If the status has no message, Squasher
  uses the span name.
* **Failed CI runs.** With the [GitHub integration](/integrations/github), a
  workflow that ends as `failure`, `error`, `action_required`, or `timed_out`
  creates an issue. Failures of the same repository, workflow, branch, and
  trigger event go into one issue. A later successful run resolves that issue
  if it is still unresolved.
* **Failed deployments.** Failed deployments from [Vercel](/integrations/vercel)
  or [Railway](/integrations/railway) create one issue per failed deployment.

For runtime errors, the issue level is `fatal` or `error`. A log with severity
number 21 or higher is `fatal`.

## How grouping works

Squasher computes a fingerprint for each runtime error. Two errors go into the
same issue when their fingerprints match in the same project.

The fingerprint uses three values:

1. The service name, from the `service.name` resource attribute.
2. The error type, from the `error.type` or `exception.type` attribute. If
   there is no error type, Squasher uses the normalized message.
3. The normalized message.

To normalize the message, Squasher:

* Keeps only the first line.
* Replaces UUIDs with `<uuid>`.
* Replaces hex values that start with `0x` with `<hex>`.
* Replaces standalone numbers with `<num>`. Numbers inside a word, such as
  `order_123`, stay.
* Collapses whitespace and keeps the first 500 characters.

For example, `User 4821 not found` and `User 97 not found` from the same service
and error type go into one issue.

Stack frames are not part of the fingerprint. Squasher stores uploaded
[source maps](/sdks/source-maps), but it does not apply them to stack traces
yet, and they do not change how errors are grouped.

The issue title is the first line of the error message, up to 500 characters.

### Merge duplicate issues

If two issues describe the same problem, merge the duplicate into the canonical
issue. New events that match the duplicate's fingerprint then count toward the
canonical issue. A merged duplicate is hidden from the normal unresolved list.
Unmerge the duplicate to restore it and send its events back to it.

## Status and priority

Each issue has one status:

| Status       | Meaning                           |
| ------------ | --------------------------------- |
| `unresolved` | The default for a new issue.      |
| `resolved`   | The issue is marked as fixed.     |
| `ignored`    | A workflow label you set by hand. |
| `muted`      | A workflow label you set by hand. |

The dashboard issue list shows `unresolved` issues by default. Filter by
status to see the others.

When a new runtime error matches an existing issue, Squasher adds it to the
event count, updates **Last seen**, and sets the status back to `unresolved`.
This happens for every status, including `resolved`, `ignored`, and `muted`. There is
no separate regression status.

Each issue also has a priority: `low`, `medium`, `high`, or `critical`. New
issues start at `medium`.

If auto-triage is on for runtime errors, Squasher assigns a new issue to the
Squasher agent when it creates the issue. Assign a person to take over. See
[AI triage](/features/ai-triage).

## Work with issues

### Dashboard

Open **Issues** in the project sidebar. You can search and filter the list by
status, level, and service.

The issue page shows the AI triage summary, event count, first and last seen
times, fingerprint, environment, service, and assignee. From the issue page you
can:

* Change **Status** and **Priority**.
* **Bookmark** or **Subscribe** to the issue for your own account.
* **Run AI triage** to start a fresh triage run.
* **Create fix** to start a fix run. See [Auto-fix](/features/auto-fix).
* Set or clear the assignee by user ID.
* **Merge duplicate** by entering the duplicate issue ID, or **Unmerge this
  issue** on a merged duplicate.

### API

Use the [Error groups API](/api-reference/errors) to list, read, and update
issues, merge and unmerge duplicates, and read related traces, suspect commits,
and triage runs. Set `status` and `priority` with
`PATCH /v1/projects/{project_id}/errors/{error_group_id}`.

### CLI

`squasher errors` (alias `squasher issues`) has these subcommands: `list`,
`get`, `update`, `triage`, and `triage-runs`.

```bash theme={null}
squasher errors list --project <project_id> --status unresolved
squasher errors update --project <project_id> <error_group_id> --status resolved
squasher errors update --project <project_id> <error_group_id> --priority high
```

### MCP

Agents can list, read, update, and triage issues through
[MCP](/integrations/mcp) with `search("errors")` followed by `execute`. Merge
and unmerge are not available through MCP.

## Related

* [AI triage](/features/ai-triage)
* [Auto-fix](/features/auto-fix)
* [Source maps](/sdks/source-maps)
* [Troubleshooting](/troubleshooting)

## Agent handoff

```text theme={null}
Review Squasher issues for project <project_id>.
Start read-only: list unresolved issues in a bounded time window, then fetch
one issue with its related traces, suspect commits, and triage runs.
Return issue ids, fingerprints, event counts, and first/last seen times.
Ask before changing status, priority, or assignee, and before merging issues.
```