# Read a bug

> See what a bug holds, how Rehearsal confirmed it and what its state means.

Source: https://rehearsal.dev/docs/bugs/read-a-bug

A bug in Rehearsal starts as a check your app failed: a subagent expected a page to do something, and the page did something else. Usually, before it counts as a bug, a second subagent sees the same thing in a fresh browser. This page shows what a bug's report holds, how a failure becomes a bug, and how to read the labels and the Bugs page.

## Where bugs appear

While an exploration runs, **Bugs** in the panel beside the chat lists the bugs its subagents have found, in the order they found them. **Bugs** in the sidebar is a page of its own with every bug of the project that you can read, and the sidebar shows beside it how many are open.

Each bug is one row: a small picture of the moment it happened, its number, such as Bug #5, and its title. Press anywhere on the row to open the bug's report. In the chat the report opens in the panel, and on the Bugs page it slides in from the right.

## What a bug holds

A report reads from the top down, like a video page:

- **The title.** One sentence that says what went wrong. In the chat, a line under it names the part of the app the subagent was exploring, with **Watch the full recording** to see everything that browser did.
- **The recording.** The browser's recording, paused at the first step of the bug, with the bug's steps marked in violet on the bar. Press play to watch it happen.
- **Steps to reproduce.** The steps that led to the bug, with the one that failed last. The report shows the last four, and **Show all 18 steps** opens the rest. Press a step to move the recording to it.
- **Expected.** What the page should have done.
- **What happened.** What the subagent saw instead, in its own words. **Copy bug description** under it puts the whole bug on your clipboard as plain text, for an issue or a message.

Under the report comes the card for fixing the bug, which [Fix a bug and check the fix](https://rehearsal.dev/docs/bugs/fix-a-bug.md) explains, then **Was this a good find?** with a thumbs up and down, and the exploration's other bugs.

## How a failure becomes a bug

Every test case a subagent checks has an expected result. When your app does something else, the check fails, but one failed check is not a bug yet, because a subagent can be wrong. So in an exploration started from setup or the chat, Rehearsal sends a second subagent to the same page in a fresh browser, signed in the same way, with the same steps and the same expected result. It is told nothing of what the first one saw. If it sees the same failure, the failure becomes a bug and takes the next number.

When the second look sees the page work, Rehearsal keeps the failure anyway, labelled **Couldn't reproduce**, so nothing a subagent saw go wrong is lost. A failure still waiting for its second look when the exploration ends is kept the same way. Both come after the bugs, under **Bugs we couldn't reproduce**, and no count includes them.

Some failures count as bugs at once, with no second look. A failure a subagent meets while it signs up as a new user is one, because the same sign-up cannot be done twice with one new account. [`rehearsal explore --second-look no`](https://rehearsal.dev/docs/reference/cli-explore.md) turns the second look off for an exploration it starts.

Layout bugs are measured rather than judged by eye. Rehearsal measures each page a subagent opens, at the width of that browser, for controls that overlap, parts past the edge of the screen, text that is cut off, a page that scrolls sideways, an image that does not load and items out of line. A subagent can report one of these only when a measurement backs it, so the title says what was measured, such as "At 768 pixels wide, Contact overlaps Log in in the header."

## What the labels mean

Most bugs carry no label, which means they stand open until someone fixes them or says they are not bugs. The rest carry a label under the title, or fold to one line:

| Label | What it means |
| --- | --- |
| **Couldn't reproduce** | Nobody saw it happen again. A second look or a test tried and did not see it, or the exploration ended before anyone could look. |
| **Fixed** | You marked the bug fixed, or Rehearsal checked the fix and the bug is gone. |
| **Not a bug** | Someone said it is not a bug. The row folds to one line and the bug moves to **Dismissed**. |
| **Same as Bug #19** | Someone said it is the same problem as another bug. It is listed under that bug and counted once. |

## The Bugs page

The Bugs page lists the bugs of the project and app chosen at the top of the page, newest first, twenty at a time with **Show more bugs**. Its pills split what explorations leave behind:

- **Bugs** holds the open bugs, with the ones under **Bugs we couldn't reproduce** after them.
- **Accessibility** and **Suggestions** hold the reports of the newest exploration, which [Suggestions and accessibility](https://rehearsal.dev/docs/bugs/suggestions-and-accessibility.md) explains.
- **Dismissed** holds the bugs marked as not a bug. It appears once there is one.

A bug's number belongs to its project. Rehearsal counts from 1 in the order it records bugs, whichever exploration found them, and a number is never given twice. Every bug takes one, including those labelled **Couldn't reproduce** and those later marked as not a bug, while a failure still waiting for its second look takes the next number only once it becomes a bug or is kept. So Bug #5 is the fifth bug Rehearsal recorded in Parcel, and the open bugs can skip numbers. Suggestions and accessibility issues have no number. The number is how you name a bug everywhere else: the prompt for your coding agent calls it bug #5, and `rehearsal bugs show 5` reads it in a terminal.

## Share a bug

**Share** at the top of a report holds two rows. **Copy link** copies a link that opens the bug's report on the Bugs page. **Create GitHub issue** opens one issue in the project's repository with the bug's title, its steps, what was expected, what happened and a link back to the bug. A bug gets one issue at most, so the row then reads **Issue #123 created** with **Open on GitHub**. A project without a repository offers **Connect GitHub to create issues** instead, and connecting one is for an admin.

> [!NOTE]
> **Who can read a bug**
>
> An exploration you start in a chat is private, as the chat is, so at first its bugs are yours alone. Once a test reproduces one of its bugs or checks a fix, everyone in the project can read that exploration and its bugs. Until then, a teammate who opens your link sees "Rehearsal could not find this bug." An exploration started from the CLI belongs to the project from the start.

## Next steps

- [Fix a bug and check the fix](https://rehearsal.dev/docs/bugs/fix-a-bug.md): Hand a bug to your coding agent, mark it fixed and have Rehearsal check it.
- [Find and fix bugs with your coding agent](https://rehearsal.dev/docs/cli/coding-agents.md): Let Claude Code, Codex or Cursor explore, fix and check each bug.
- [Suggestions and accessibility](https://rehearsal.dev/docs/bugs/suggestions-and-accessibility.md): Read the two reports an exploration leaves besides its bugs.
- [Watch an exploration](https://rehearsal.dev/docs/reagent/browser.md): Follow the subagents, their browsers and the cases they check.
