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

# Issues

An issue is a failure pattern that Foveus detects from executions.

Instead of treating every failed request as a separate problem, Foveus groups related failures so you can focus on what needs investigation.

For example, if the same endpoint repeatedly returns HTTP 500, Foveus can group those failed executions into one issue:

```text theme={null}
HTTP 500 in orders-api
```

## Why issues matter

Executions show individual units of work.

Issues show patterns.

Use issues when you want to answer:

* What is failing?
* Where is it happening?
* How often is it happening?
* Which execution should I inspect first?
* Is this active, resolved, or recurring?
* Who owns the follow-up?

## How Foveus creates issues

Foveus analyzes failed or suspicious executions and groups them by meaningful signals.

Signals can include:

* service
* endpoint or operation
* failure type
* HTTP status code
* exception type
* outcome semantics
* common factors
* failure signature

The exact grouping depends on the telemetry captured for the execution.

## Issue lifecycle

An issue can move through different states.

| State      | Meaning                                                              |
| ---------- | -------------------------------------------------------------------- |
| `active`   | Foveus has detected an unresolved failure pattern.                   |
| `resolved` | The issue was marked as resolved.                                    |
| `reopened` | The same or related failure pattern appeared again after resolution. |

During private beta, some lifecycle behavior may still be manual or evolving.

## Issue severity

Foveus may show a severity signal such as:

| Severity   | Meaning                                  |
| ---------- | ---------------------------------------- |
| `info`     | Low urgency or informational signal.     |
| `warn`     | Something needs review.                  |
| `critical` | A high-impact or severe failure pattern. |

Severity helps triage, but it should not replace investigation. Always inspect the evidence and linked executions.

## Failure types

Failure type explains the kind of problem Foveus detected.

Common examples:

| Failure type       | Meaning                                                             |
| ------------------ | ------------------------------------------------------------------- |
| `http_error`       | The execution returned an HTTP failure response.                    |
| `exception`        | The execution failed because of an exception.                       |
| `timeout`          | The execution exceeded an expected time limit.                      |
| `business_rule`    | The execution returned a business-level failure.                    |
| `provider_failure` | The execution failed because of an external or downstream provider. |

The exact values may depend on your service and outcome semantics configuration.

## Issue detail

Open an issue to inspect its evidence.

An issue detail page can include:

* failure pattern
* suggested fix or next diagnostic step
* common factors
* representative execution
* linked executions
* recent activity
* lifecycle
* comments
* activity history
* technical metadata

The representative execution is usually the best place to start. It gives you a concrete failed execution to inspect.

## Linked executions

An issue can have one or more linked executions.

Linked executions show the individual requests, jobs, or operations that matched the issue pattern.

Use linked executions to inspect:

* request context
* response context
* timeline
* logs
* outcome
* duration
* failure evidence

## Representative execution

When available, Foveus highlights a representative execution for the issue.

This is the execution you should inspect first.

A representative execution helps you move from:

```text theme={null}
This issue happened.
```

to:

```text theme={null}
This is the exact execution that shows what happened.
```

## Common factors

Common factors explain what Foveus found across related executions.

Examples:

```text theme={null}
Endpoint: POST /orders
Status code: 500
Failure type: http_error
Source: web
```

Common factors help you understand why executions were grouped together.

## Comments

Use comments to record triage notes.

Good comments include:

* root cause
* next step
* owner
* expected fix time
* decision
* deployment note

Example:

```text theme={null}
Next step: inspect the downstream inventory provider response for failed order creation requests.
```

## Activity history

The activity tab shows changes made to the issue.

This can include:

* comments
* assignment changes
* status changes
* resolution
* reopening

Use activity history when you need to understand what changed and when.

## Search issues

Use the Issues page to find active or historical issue patterns.

Common searches:

```text theme={null}
service:orders-api
```

```text theme={null}
status:active
```

```text theme={null}
failureType:http_error
```

```text theme={null}
issueId:313
```

You can combine filters when supported:

```text theme={null}
service:orders-api status:active
```

## Issues vs executions

Issues and executions answer different questions.

| Use                                                  | Go to        |
| ---------------------------------------------------- | ------------ |
| Find a specific request, job, or operation           | Executions   |
| Search by customer ID, request ID, or business value | Executions   |
| Investigate a repeated failure pattern               | Issues       |
| See all executions linked to a failure pattern       | Issue detail |
| Record triage notes and ownership                    | Issue detail |

## When to use issues

Use issues when:

* several executions fail in the same way
* a failure keeps recurring
* you need to assign ownership
* you want to track resolution
* you want to move from a pattern to evidence

Use executions when:

* you are investigating a single support complaint
* you know a business identifier such as `customerId`
* you know a request ID, trace ID, or execution ID
* you need request or response context

## What to do next

* Learn about executions: [Executions](/concepts/executions)
* View your first execution: [View your first execution](/get-started/view-your-first-execution)
* Investigate a user complaint: [Investigate a user complaint](/guides/investigate-user-complaint)
* Debug an HTTP 500: [Debug an HTTP 500](/guides/debug-http-500)