Skip to content

The only tool you need to know what is happening and how to fix it.

2.9 KB
Raw Blame
# Exceptions

Capture JavaScript errors and exceptions with full stack traces.

## captureException

Capture an error with its stack trace:

```javascript
import { captureException } from "@tracewayapp/frontend";

try {
  riskyOperation();
} catch (error) {
  captureException(error);
}
```

The SDK extracts the error type, message, and stack trace automatically.

## captureExceptionWithAttributes

Capture an error with additional metadata:

```javascript
import { captureExceptionWithAttributes } from "@tracewayapp/frontend";

try {
  processOrder(orderId);
} catch (error) {
  captureExceptionWithAttributes(error, {
    orderId: orderId,
    userId: currentUser.id,
    action: "checkout",
  });
}
```

Attributes appear as tags in the Traceway dashboard, making it easier to filter and debug issues.

## Attribute Best Practices

**Do include:**
- User identifiers (anonymized if needed)
- Request/transaction IDs
- Feature flags or A/B test variants
- Relevant business context (order ID, product ID, etc.)

**Avoid including:**
- Sensitive data (passwords, tokens, PII)
- Large objects or arrays
- Circular references

## Error Types

The SDK handles various JavaScript error types:

```javascript
// Standard Error
captureException(new Error("Something went wrong"));

// TypeError
captureException(new TypeError("Cannot read property 'x' of undefined"));

// Custom errors
class ValidationError extends Error {
  constructor(message) {
    super(message);
    this.name = "ValidationError";
  }
}
captureException(new ValidationError("Invalid email format"));
```

The type shown in Traceway comes from the error's **class name**, not from `this.name`. Minifiers rename classes, so in a production build the issue above reads `r: Invalid email format` rather than `ValidationError: Invalid email format`. Put anything you need to search or group on into the message or into attributes.

## Non-Error Values

Pass real `Error` objects. The SDK reads only the value's class name and its `message` property, so anything else loses information and arrives with no stack trace:

```javascript
// Message is lost. Stored as "String: undefined".
captureException("Something went wrong");

// Stored as "Object: Server error". The `code` field is dropped.
captureException({ code: 500, message: "Server error" });
```

Wrap the value in an `Error` instead, and pass the extra fields as attributes:

```javascript
import { captureExceptionWithAttributes } from "@tracewayapp/frontend";

captureExceptionWithAttributes(new Error("Server error"), { code: "500" });
```

## React Error Boundaries

For React applications, use the `@tracewayapp/react` package. Its `<TracewayProvider>` itself acts as an error boundary: render-time exceptions are captured automatically and re-thrown so the app behaves exactly as without Traceway. See the [React documentation](/client/react) for setup, or the [Error Boundary page](/client/react/error-boundary) if you need a custom fallback UI for a specific subtree.