# Report Bug

> Bundle the requests behind a bug into a redacted HAR, a Markdown summary with the failing requests and cURL repros, a replayable flow and a Simulator or Android screen recording, then save it or file it in GitHub, Jira or Linear.

Source: https://docs.subcloak.com/cloak-proxy/sessions/report-bug/

Added in Cloak Proxy 0.4.0.

The hardest part of a bug report is the evidence. **Report Bug** turns the requests behind a bug into everything a developer needs:

- a summary that lists the failing requests first, each with its response, trace and a cURL command to reproduce it;
- a redacted HAR and Cloak Proxy session;
- a flow that replays the requests;
- if you like, a recording of the Simulator or Android screen while it happened.

Save the bundle as a .zip, or file it as an issue in GitHub, Jira or Linear with your own token. Nothing leaves your Mac until you click **File**.

*[Screenshot: The Report Bug window: on the left, the title Checkout fails with 502 after applying a gift card, what happened, steps to reproduce and expected result, the requests to include, and switches for redaction, HAR, session, replayable flow and cURL; on the right, the README.md summary and the files of the bundle with their sizes; at the bottom, Save to Disk, GitHub, Jira and Linear, and a Save Bundle button. Describe the bug on the left; the right shows exactly what goes in the bundle.]*

## Open Report Bug

| Where | Which requests |
|---|---|
| Select requests, right-click and choose **Report Bug…** (or **Report Bug with N Requests…**) | The selected requests |
| **Tools › Report Bug…** (<kbd>⇧</kbd> <kbd>⌥</kbd> <kbd>⌘</kbd> <kbd>B</kbd>) | The selected requests, or, with none selected, the last five minutes of the app in the sidebar |

In the window, under **Requests**, switch between the selection and **Recent**: the last 1 to 60 minutes of one app or every app. Recent requests keep coming in while the window is open, so you can reproduce the bug with the window already set up.

## Write the report

1. Give it a **Title**. If the requests include a failure, Cloak Proxy suggests one, such as `POST /v2/checkout fails with 502`.
2. Fill in **What happened**, **Steps to reproduce** and **Expected**. Leave any of them empty and they're left out.
3. Choose what to include (see [What's in the bundle](#whats-in-the-bundle)). Leave **Redact tokens, cookies, passwords and keys** on unless everyone who'll read the report may see them.
4. Optionally, [record the screen](#record-the-screen) while you reproduce the bug.
5. Check the summary on the right. It updates as you type and as requests arrive. **Copy Summary** copies the Markdown.
6. [Save it](#save-the-bundle) or [file it](#file-it-in-github-jira-or-linear).

## What's in the bundle

The bundle is a .zip with one folder named after the title:

- checkout-fails-with-502/
  - README.md
  - requests.har
  - requests.cloaksession
  - replay/
    - collection.json
    - flow.json
  - reproduce.sh
  - browser-console.json
  - screen-recording.mp4

| File | What it is | Switch |
|---|---|---|
| `README.md` | The summary below. It's also the issue's description when you file it. | Always |
| `requests.har` | Every request and response. Opens in browser dev tools, Charles, Proxyman and Cloak Proxy. | **HAR file** |
| `requests.cloaksession` | The same as a Cloak Proxy session, with timings and apps. Open it with **File › Open Session…**. | **Cloak Proxy session** |
| `replay/collection.json`, `replay/flow.json` | The requests as an [API-client](https://docs.subcloak.com/cloak-proxy/api-client/overview/) collection and a [replayable flow](https://docs.subcloak.com/cloak-proxy/api-client/run/replayable-flows/) that carries IDs and tokens from one response to the next request. | **Replayable flow for the API client** |
| `reproduce.sh` | A cURL command for each failing request. | **cURL commands for failing requests** |
| `browser-console.json` (added in Cloak Proxy 0.4.1) | Console errors from your browser tabs, with their stacks, if the [browser extension](https://docs.subcloak.com/cloak-proxy/devices/browser-extension/) is paired. | Always, when there are any |
| `screen-recording.mp4` | The screen recording, if you made one. | [Screen recording](#record-the-screen) |

### The summary

`README.md` puts the failing requests first, because that's what a developer reads first.

| Part | What it shows |
|---|---|
| Your description | **What happened**, **Steps to reproduce** and **Expected**. |
| Facts table | The app and its version (from its `User-Agent`), the device for requests from an iPhone or Android device, when the requests were captured, how many failed, the hosts, which requests were included, and Cloak Proxy's version. |
| **Failing requests** | Each request with a `4xx` or `5xx` status, no response, or an [API contract](https://docs.subcloak.com/cloak-proxy/testing/contract-checking/) error. For each one: when it happened (and how far into the screen recording), how long it took, the app, its [trace ID](https://docs.subcloak.com/cloak-proxy/inspect/distributed-tracing/) with **Open in …** links and any broken propagation, contract errors, the Sentry error report it caused, the start of the response body (pretty-printed JSON), and a cURL command. Up to 15 are listed in full. |
| **Sentry error reports** | Error reports the app sent to Sentry that couldn't be matched to a failing request. |
| **Browser console** (added in Cloak Proxy 0.4.1) | Uncaught errors and rejected promises from browser tabs, from a minute before the first request to a minute after the last, with the script and line. Up to 20. Needs the [browser extension](https://docs.subcloak.com/cloak-proxy/devices/browser-extension/). |
| **Timeline** | Every request in order, with its time from the start (or from the start of the recording), status and duration. Failures are in bold. Up to 200 rows; the HAR has the rest. |
| **Files** | What each file in the bundle is. |

> **Sentry error reports are matched for you:**
> When an app sends an error to Sentry (`/api/<project>/envelope/` or `/store/`, on sentry.io or your own Sentry), Cloak Proxy reads the error's type and message and attaches it to the failing request the same app sent up to 30 seconds earlier. The report then shows which API call caused which crash or error.

### Redaction

With **Redact tokens, cookies, passwords and keys** on, every file in the bundle goes through the same [redaction](https://docs.subcloak.com/cloak-proxy/sessions/redaction/) as exports: credential headers, cookies, password and token fields, credential query parameters and anything the secret scanner recognises become `REDACTED`. This includes the summary, the cURL commands and Sentry messages. Turn it off only when everyone who'll read the report may see those values; the window warns you while it's off.

The cURL commands in a redacted report don't work as they are: replace each `REDACTED` with a real value first. `reproduce.sh` says so at the top.

## Record the screen

1. Boot the Simulator you're testing in, or connect an Android device or emulator with USB debugging on.
2. Under **Screen recording**, choose it and click **Start**.
3. Reproduce the bug.
4. Click **Stop** (<kbd>⌘</kbd> <kbd>.</kbd>). The recording is added as `screen-recording.mp4`, and the summary's times now count from the start of the video, so `+0:13` in the timeline is 13 seconds into the recording.

Simulators are recorded with Xcode's `simctl`, and Android devices with `adb screenrecord`, which stops after three minutes. **Remove** drops the recording.

## Save the bundle

With **Save to Disk** selected at the bottom, click **Save Bundle…** (<kbd>⌘</kbd> <kbd>S</kbd>) and choose where. Cloak Proxy shows the .zip in Finder, ready to attach to an issue, an email or a chat.

## File it in GitHub, Jira or Linear

Choose **GitHub**, **Jira** or **Linear** at the bottom. The first time, click **Set Up** *tracker***…** and enter where to file and your token.

*[Screenshot: The Jira settings sheet: site https://storefront.atlassian.net, project key SHOP, issue type Bug, email ada@example.com, labels, a token field saved in the Keychain, and help on where to create an API token. Each tracker is set up once. Tokens are kept in the Keychain.]*

| Tracker | You enter | What filing does |
|---|---|---|
| GitHub | The repository (`owner/name`), the API address for GitHub Enterprise, labels, and a fine-grained token with **Issues: Read and write** | Creates an issue with the summary. GitHub can't take attachments through its API, so drag the .zip onto the issue afterwards, or turn on **Also upload the HAR as a secret gist** (the token then needs the gist scope) to link the HAR from the issue. |
| Jira | Your site (`https://example.atlassian.net`), the project key, the issue type (**Bug** by default), labels, your account's email and an API token | Creates the issue with the summary converted to Jira's formatting, and attaches the .zip. |
| Linear | The team key (such as `ENG`) and a personal API key | Uploads the .zip, then creates the issue with the summary and a link to the bundle. |

Then click **File in GitHub**, **File in Jira** or **File in Linear** (<kbd>⌘</kbd> <kbd>Return</kbd>). When it's done, a link to the new issue appears next to the button.

> **Nothing is sent without your click:**
> Report Bug only contacts a tracker when you click **File**. It talks to the tracker directly, never through the proxy, and only sends the bundle you see in the window. GitHub uses the same token as [Publish to Gist](https://docs.subcloak.com/cloak-proxy/sessions/publish-to-gist/). **Remove Token** in the tracker's sheet deletes it from the Keychain.

## AI assistants and the command line

An assistant connected to the [MCP server](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/) can build a bundle with `make_bug_report`: pick requests by id, or the last few minutes of an app, give a title and description, and it saves the .zip and returns the summary. It can't file the report. With `review: true` it opens the Report Bug window filled in, so you can check it and click **File** yourself. See the [MCP tools reference](https://docs.subcloak.com/cloak-proxy/automation/mcp-tools-reference/#make_bug_report).

`cloakctl report` builds the same bundle from a saved session or HAR, for example from a CI recording:

```bash title="Terminal"
cloakctl report --har run.har --title "Checkout fails with 502" --description "Nightly UI tests" --out reports/
cloakctl report --from-app --app ShopApp --minutes 10 --title "Login loops" --out ~/Desktop/
```

| Option | What it does |
|---|---|
| `--session FILE`, `--har FILE` | The requests to report. |
| `--from-app` | Use the running app's captured traffic instead. |
| `--ids 3,7,12` | Only these requests. |
| `--app NAME`, `--minutes N` | Only one app's requests, or the last N minutes. |
| `--title`, `--description`, `--steps`, `--expected` | The report's words. `--title` is required. |
| `--out FILE.zip` or `--out DIR` | Where to write the bundle. By default, the current folder. |
| `--no-redact`, `--no-har`, `--no-session`, `--no-replay`, `--no-curl` | Leave something out. |
| `--markdown` | Print only the summary. |

## Limits

- A request counts as failing when it got a `4xx` or `5xx`, no response at all, or an API contract error. A `200` with an error in its body isn't flagged: select it and describe it yourself.
- The bundle includes the response bodies Cloak Proxy captured, up to the body size limit in the proxy settings.
- Redaction removes credentials, not personal data such as names and emails. Check the summary before filing in a tracker people outside your team can read.
- Screen recording needs Xcode for Simulators and adb for Android. Physical iPhones can't be recorded.

## Related

  - [Redaction](https://docs.subcloak.com/cloak-proxy/sessions/redaction/): What's removed from exports and reports.
  - [Publish to Gist](https://docs.subcloak.com/cloak-proxy/sessions/publish-to-gist/): Share requests as a GitHub gist.
  - [Distributed tracing](https://docs.subcloak.com/cloak-proxy/inspect/distributed-tracing/): Trace IDs and links in the report.
  - [Replayable flows](https://docs.subcloak.com/cloak-proxy/api-client/run/replayable-flows/): Run the bundle's flow in the API client.