# Crash reports

## Summary

When the web app hits an error it did not expect, it tells Talewright on its
own: what the error said, where in the code it happened, which page was open
and which version of the app was running. The people who run Talewright read
these reports to find and fix crashes.

Nobody has to do anything. There is no dialog and nothing to switch on.
To tell the team something in your own words, use
[Giving feedback](feedback.md).

## Who can do what

| Action | Signed-out visitor | Signed-in person | API key or connected app |
| --- | --- | --- | --- |
| Send a crash report | No: `UNAUTHENTICATED` | Yes, verified or not, in any organization or in none | No: `FORBIDDEN`, reason `SESSION_REQUIRED` |
| Read a crash report back | No | No | No |

- Owners and admins do not see the reports their members' browsers send.
- Sending a crash report is not an MCP tool. No credential scope grants it.

## How it works

### What a report holds

- **`message`**: the error's message. Required, at most 1 KiB.
- **`stack`**: where in the app's code the error happened. Optional, at most
  8 KiB.
- **`route`**: the path of the page that was open, such as
  `/w/<workspaceID>/files`. Optional, at most 512 bytes.
- **`release`**: the version of the web app. Optional, at most 128 bytes.
- **`organizationID`**: the organization of the workspace that was open.
  Optional.
- Talewright adds who sent the report and when.

### What is kept out

- The address's query string and fragment are dropped from `route`.
- Values after `token=`, and OAuth `code=` and `state=` values, are replaced
  with `[Filtered]` in every field.
- Email addresses are replaced with `[Filtered]`.
- Quoted text that holds a space or is longer than 40 characters is replaced
  with `[Filtered]`, because errors can quote the text they failed on. A short
  quoted name, such as `'map'`, is kept.
- The organization is kept only when the person is a member of it.
- Nothing else about the request is kept: no email address, no IP address,
  no file content.

### When the app sends one

- An error that nothing in the app caught.
- A promise that failed and that nothing in the app handled.
- An error that left a page unable to load, shown as "This page could not
  load".
- A request the server refused or failed is not sent as a crash report.
  Talewright already knows about server failures, and refusals are answers,
  not crashes.

### How often

- The app sends each distinct error once per page load.
- It sends at most five reports per page load.
- A report that fails to send is dropped. The app never tries again and
  never shows a message about it.
- One person's browsers send at most 10 reports a minute together. More
  are refused with `RATE_LIMITED`.

## In the app

Crash reports have no screen. When a page cannot load, the app shows "This
page could not load" with "Try again"; the crash report goes out on its own.

## For agents

Crash reports are for the web app in a browser. They are not an MCP tool.

| Operation | Capability ID | Access | MCP |
| --- | --- | --- | --- |
| `POST /v1/client-errors` | `account.client_errors.report` | session only | none |

- The answer to a report that was accepted is `202` with no body.
- A valid bearer token is refused with `403 FORBIDDEN`, `details.reason`
  `SESSION_REQUIRED`.
- The request carries the session cookie and an `Origin` header equal to the
  app's origin, as every change from a browser session does. See
  [The REST API](../agents/rest-api.md#signing-in-with-a-browser-session).

Example body:

```json
{
  "message": "Cannot read properties of undefined (reading 'map')",
  "stack": "TypeError: Cannot read properties of undefined (reading 'map')\n    at FileList (https://app.usetalewright.com/assets/index.js:1:2345)",
  "route": "/w/0199a1b2-0000-7000-8000-000000000001/files",
  "release": "0f3c2a9",
  "organizationID": "0199a1b2-0000-7000-8000-000000000002"
}
```

## Edge cases

- **A field is too long.** The app cuts each field to its limit before
  sending. A request that sends a longer field is refused with
  `VALIDATION_FAILED` on that field, and nothing is kept.
- **Limits count bytes, not characters.** A letter such as "é" counts as two
  bytes, so 1 KiB holds 512 of them.
- **The message is empty or only spaces.** The app sends "Unknown error"
  instead. A request with an empty message is refused with
  `VALIDATION_FAILED` on `message`.
- **The person is signed out.** Pages without a session, such as sign-in and
  password reset, cannot send crash reports. The request is refused with
  `UNAUTHENTICATED` and the app drops it.
- **The organization is not the person's.** The report is accepted and kept
  without it.
- **The same error happens again after a reload.** A reload starts a new page
  load, so the app sends it once more.
- **An unknown field.** A body with a field not listed above is refused with
  `VALIDATION_FAILED`.

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | No session. | Sign in. |
| `FORBIDDEN` | 403 | A bearer credential (`SESSION_REQUIRED`), or the `Origin` header is not the app's origin. | Send from the web app. |
| `PAYLOAD_TOO_LARGE` | 413 | The body is over 64 KiB. `details.limitBytes` is 65536. | Send shorter fields. |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | The body is not JSON. | Send `Content-Type: application/json`. |
| `VALIDATION_FAILED` | 422 | A field is over its limit, the message is empty, or the body has an unknown field. `details.field` names the field. | Shorten or remove the field. |
| `RATE_LIMITED` | 429 | More than 10 reports in a minute. | Wait for `Retry-After`. |

## Limits

| Limit | Value | Past the limit |
| --- | --- | --- |
| `message` | 1 byte to 1 KiB | `422 VALIDATION_FAILED` on `message` |
| `stack` | Up to 8 KiB | `422 VALIDATION_FAILED` on `stack` |
| `route` | Up to 512 bytes | `422 VALIDATION_FAILED` on `route` |
| `release` | Up to 128 bytes | `422 VALIDATION_FAILED` on `release` |
| Body of a report | Up to 64 KiB | `413 PAYLOAD_TOO_LARGE` |
| Reports sent by one person, refused ones included | 10 in 1 minute | `429 RATE_LIMITED` |
| Reports one page load sends | 5, each distinct error once | Not sent |

## Questions and answers

### Do I need to turn crash reports on?

No. The app sends them on its own while you are signed in.

### Can I see what was sent?

No. Crash reports cannot be read back. The browser's developer tools show the
request to `/v1/client-errors`.

### Does a crash report include my files or what I typed?

No. It holds the error's message and stack, the page's path, the app's
version and the organization you had open. Quoted text, email addresses and
link tokens are replaced with `[Filtered]` before the report is kept.

### Can my organization's admins read my crash reports?

No. Only the people who run Talewright read them.

### Should I still give feedback about a crash?

Yes, if you can say what you were doing. A crash report says where the app
failed, not what you were trying to do. Use [Giving feedback](feedback.md).

## Related pages

- [Giving feedback](feedback.md)
- [Limits](../reference/limits.md)
- [Errors](../reference/errors.md)
- [Roles and permissions](../reference/permissions.md)
