# Problems

> What a problem is, what makes two failures the same problem, and exactly when a problem is new, growing, resolved, ignored or back.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/concepts/problems/

This page is for anyone who reads Sypnia's problems list, and for anyone who builds on it. Grouping, counting and status are part of the open-source engine and work the same on Sypnia Cloud. The sentence in plain words needs the agent, which is included in the Cloud and uses your own model key on the engine.

A problem is a group of failures with one cause, told in one sentence. Sypnia says «problem», never «issue». Four hundred people hitting the same bug is one problem with four hundred people, not four hundred e-mails.

## What counts as a failure

| Failure         | Precisely                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A browser error | An error nobody caught, a promise rejected with no handler, an error caught by your framework's error screen, or an error you report yourself.                                                                   |
| A server error  | An exception thrown while your server handles a request, reported by a server SDK or by OpenTelemetry. With the Node and Next.js SDKs, also what your code writes to `console.error` while it handles a request. |
| A failed call   | A call that fails without throwing an error: it gets no answer, answers `400`, or answers `500` or above. This applies to the page calling your API, and to your server calling a database or another service.   |
| A timeout       | A request to your server that is still running after 20 seconds and never finishes (Node and Next.js SDKs).                                                                                                      |

These are **not** failures, and never open a problem on their own:

- Answers such as `401`, `403`, `404`, `409` or `422`. They are usually your app saying no on purpose: wrong password, missing page, invalid form. Sypnia counts them in [Performance](https://docs.sypnia.com/concepts/performance) as rejected calls.
- Rage clicks, dead clicks and form failures. They are shown on their own pages, attached to problems as evidence, and used in the weekly suggestions.
- A slow page or a slow call. See [Performance](https://docs.sypnia.com/concepts/performance).
- Your app not answering at all. That is an outage. See [Uptime](https://docs.sypnia.com/concepts/uptime).

## What makes two failures the same problem

Each failure gets a **fingerprint** where it happens, in the SDK. Failures with the same fingerprint, in the same project and environment, are the same problem.

**For an error**, the fingerprint is made of three things:

1. The error's name, such as `TypeError`.
2. Its message with everything that varies removed: numbers, quoted values, addresses, UUIDs and long ids. `Order 8841 not found` and `Order 8842 not found` are the same message.
3. The first line of the stack that belongs to **your own code**: its function and its file, without the hashes a build adds to file names. Lines from libraries, from the framework's runtime and from browser extensions are skipped.

**For a failed call**, the fingerprint is made of the call that failed (its name or target), how it failed (the status or the error code), and the method and route of the request it happened in.

**For a timeout**, it is the method and route of the request.

Because of this, the same bug is one problem across people, browsers, devices and releases. A different message or a different line of your code is a different problem.

### One request, one problem

A failure in the browser and the failure behind it on the server share a trace. Sypnia keeps them as one problem: the deepest failure in the trace is the problem, and what the person saw is listed inside it as evidence.

In the shop, the page's call to `POST /api/checkout` answers 400 because, on the server, the call to the payment service answered 400. That is one problem, about the payment call. If the shop had only the browser SDK, the page's failed call would be the problem.

## What a problem counts

| Count                 | Meaning                                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Occurrences           | How many times the failure happened. The same error from the same page within 5 seconds counts once.                       |
| People                | Identified persons, plus one for each device whose sessions were never identified. This is the «3 people» of the sentence. |
| Sessions              | Sessions in which it happened. Failures that only your server saw have no session.                                         |
| First seen, last seen | The time of the first and the latest occurrence.                                                                           |
| Release first seen in | The release of the first occurrence. This is how Sypnia says «since yesterday's change».                                   |

A new problem appears within 2 minutes of its first event. Its counts are complete within 10 minutes.

## Status: open, resolved, ignored

A problem has exactly one status. A person changes it in the app or the Console; an API token can resolve and reopen a problem with the `read` scope, and needs `admin` to ignore one. Sypnia changes the status by itself in one case: when a resolved problem happens again.

| Status       | Meaning                                                                   | Alerts | What a new occurrence does                                                                |
| ------------ | ------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
| **Open**     | It is happening, or nobody has said otherwise. Every problem starts open. | Yes    | It is counted.                                                                            |
| **Resolved** | Someone says it is fixed.                                                 | No     | The problem **reopens by itself** and is marked «came back». Resolving too early is safe. |
| **Ignored**  | Known and accepted.                                                       | Never  | It is counted. The problem stays ignored and never reopens by itself.                     |

You can reopen a resolved or ignored problem by hand at any time.

Sypnia does not resolve problems on its own. A problem that stops happening stays open, with an older «last seen», until someone resolves it.

## Marks: new, growing, came back

On top of its status, an open problem can carry marks. Sypnia computes them; you do not set them.

| Mark          | Rule                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **New**       | Its first occurrence was less than 24 hours ago.                                                                                           |
| **Growing**   | The number of people it has hit reaches at least **twice** what it was at its last alert, and at least **5**. The mark stays for 24 hours. |
| **Came back** | It was resolved, and then happened again. The mark stays until the problem is resolved again.                                              |

An example of «growing»: a problem alerts when it is new, with 1 person. At 5 people it is growing: twice 1, and at least 5. It is growing again at 10 people, then at 20. A problem that goes from 1 person to 3 is not growing: fewer than 5. Both numbers can be changed in the project's alert rules.

> **Note: Old tabs, and how to keep them from bringing a problem back**
>
> After you deploy a fix, a customer whose tab still runs the old release can hit the bug once more. When you resolve a problem you can name the release that carries the fix. Then only a failure in that release, or a later one, reopens the problem. Without a release, any new occurrence reopens it.

Each mark creates an alert when Sypnia sets it: once when a problem is new, once each time it comes back, and once for each step of growth. See [Alerts and the daily summary](https://docs.sypnia.com/concepts/alerts-and-daily-summary).

## The sentence

Before the agent has run, a problem has a **technical title**, built from the failure:

```text
createPayment answered 400 in POST /api/checkout
```

The agent runs when a problem is new, when it comes back, when it grows, and when someone asks for a new analysis. It reads the grouped failure, the stack with source lines, what the person did before, the trace, the release and what changed, and how many people and sessions it hit. It writes:

- one **sentence** in plain words, which becomes the problem's title,
- who it hit and since when,
- the likely cause, with its evidence,
- what to do,
- a confidence level,
- the prompt for your coding agent.

The agent never reads replay pixels or typed input, and never merges code. [How the analysis works](https://docs.sypnia.com/agent/how-the-analysis-works) has the details.

|                                 | Sypnia engine (open source, self-hosted)                                         | Sypnia Cloud (paid service, with a free tier)                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Grouping, counts, status, marks | Yes.                                                                             | Yes.                                                                                                                                                               |
| The sentence and the analysis   | With your own model key. Until you set one, problems keep their technical title. | Included, up to the plan's analyses a day.                                                                                                                         |
| The fix                         | The prompt and the MCP server.                                                   | The prompt and the MCP server. On the Builder and Team plans, also a pull request opened by the Sypnia GitHub App, once you turn pull requests on for the project. |

## What stays inside a problem

- One full example of the failure: message, stack, page, release. With source maps the stack shows your own files and lines. See [Releases and source maps](https://docs.sypnia.com/concepts/releases-and-source-maps).
- Recent sessions where it happened, with their replays.
- The trace of an occurrence.
- Occurrences, people and sessions for each day.

The examples, sessions and traces expire with your data's retention. The problem itself, with its sentence, status and daily counts, is kept for as long as the project exists, so Sypnia can still say «came back» months later. See [Data location and retention](https://docs.sypnia.com/cloud/data-location-and-retention).

## Example: the Pay button

Yesterday at 18:40 the shop deployed release `4f2a91c`, which renamed `cart.total` to `cart.totalCents`. The checkout still reads the old name.

1. **Today, 09:12.** A customer clicks Pay. The payment service answers 400 because the amount is missing. Within 2 minutes Sypnia opens a problem, marked **new**, with 1 person. An alert goes out.
2. **09:14.** The agent has read it. The title becomes a sentence, and the problem names release `4f2a91c` as the first one it was seen in.
3. **By 16:00.** Two more customers hit it. Same call, same answer, same route: same problem. It now reads «3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.»
4. **16:30.** You merge the fix and mark the problem **resolved**.
5. **Three weeks later.** Another change breaks the amount again. The same failure arrives, the problem reopens by itself, marked **came back**, and a new alert goes out.

## Reference

The fields of a problem and the calls to list, read, resolve and ignore one are in the [API reference](https://docs.sypnia.com/api/problems). How grouping is built is in [Problem grouping](https://docs.sypnia.com/architecture/problem-grouping).
