# What Types of Errors Does Web-Tracing Capture by Default?

> Discover what errors web tracing captures by default, including resource loading failures, JS exceptions, and more. Enhance your debugging with m-cheng-web/web-tracing.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: deep-dive
- Published: 2026-03-06

---

**Web-tracing captures four types of runtime errors—resource loading failures, uncaught JavaScript exceptions, unhandled Promise rejections, and explicit `console.error` calls—but only after explicitly enabling the error module via `options.error.core = true`.**

Web-tracing is an open-source JavaScript monitoring SDK designed to track application health in real time. Understanding what types of errors web-tracing captures by default is essential for configuring comprehensive client-side observability. While the SDK provides hooks for these four error categories, error collection remains inactive until developers explicitly opt-in through the initialization options.

## The Four Error Types Captured by Web-Tracing

Once enabled, web-tracing instruments the browser environment using handlers defined in [`packages/core/src/lib/replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/replace.ts). The library monitors four distinct error channels that cover both runtime failures and developer-generated error signals.

### 1. Resource Loading Errors

Web-tracing detects when external assets fail to load, including broken images, missing scripts, failed CSS fetches, and unsuccessful API requests. These errors are captured via the global `error` event using the `listenError` function implemented in [`src/lib/replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/src/lib/replace.ts)【replace.ts】【13‑22】. When a resource fails to load, the browser bubbles an `ErrorEvent` containing the target element and URL, which web-tracing normalizes into a structured error report.

### 2. Uncaught JavaScript Exceptions

Synchronous runtime errors—such as reference errors, type errors, or custom thrown exceptions—are captured through the same global `error` event listener. The `listenError` implementation parses the `ErrorEvent` object to extract critical debugging context including the error message, stack trace, line number, and column number【replace.ts】【13‑22】. This covers scenarios like calling undefined functions or accessing properties on null values.

### 3. Unhandled Promise Rejections

Asynchronous errors that reject without a corresponding `.catch()` handler trigger the `unhandledrejection` event. Web-tracing registers `listenUnhandledrejection` in [`replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/replace.ts) to intercept these rejections before they become uncaught exceptions【replace.ts】【24‑31】. The listener captures the rejection reason and stack trace, ensuring that failed network requests, database operations, or async computations don't silently fail in production.

### 4. Console Error Calls

Beyond runtime failures, web-tracing instruments `console.error` via the `replaceConsoleError` function to capture explicit error logging from application code【replace.ts】【33‑47】. This wrapper intercepts calls to `console.error`, forwards the original message to the browser console, and additionally emits the data to web-tracing's internal event bus for aggregation. This captures semantic errors that developers intentionally log but which might not trigger actual exceptions.

## How Error Capture Is Configured

Error tracking is governed by the `error` configuration object defined in [`packages/core/src/lib/options.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts). By default, both the `core` (client-side) and `server` (server-side) error flags are set to `false`, meaning no error listeners are attached during initialization until explicitly enabled.

```typescript
import { initOptions } from '@web-tracing/core'

// Enable client-side error capture
initOptions({
  dsn: 'https://example.com/trace',
  appName: 'my-app',
  error: { 
    core: true,   // Capture browser errors
    server: true  // Capture server-side errors (if applicable)
  }
})

```

According to the source code in [`packages/core/src/lib/options.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/options.ts), the default state leaves error modules inactive to prevent unintentional data collection during development or testing phases.

## Practical Examples of Error Capture

The following patterns demonstrate how each error type triggers web-tracing's reporting mechanism once `error.core` is enabled:

```typescript
import { initOptions } from '@web-tracing/core'

initOptions({
  dsn: 'https://example.com/trace',
  appName: 'demo-app',
  error: { core: true, server: false }
})

// 1. Resource loading error (caught by listenError)
const img = document.createElement('img')
img.src = '/non-existent-image.png'

// 2. Uncaught JavaScript exception (caught by listenError)
setTimeout(() => {
  undefinedFunction()  // Throws ReferenceError
}, 0)

// 3. Unhandled Promise rejection (caught by listenUnhandledrejection)
new Promise((resolve, reject) => {
  reject(new Error('Async operation failed'))
})
// Note: No .catch() attached

// 4. Console error call (caught by replaceConsoleError)
console.error('Application state corrupted:', { userId: 123 })

```

The test suite in [`packages/core/__test__/err.spec.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/__test__/err.spec.ts) validates that each of these scenarios correctly generates error events with appropriate metadata including stack traces, timestamps, and error categories.

## Summary

- **Resource loading errors** are captured via the global `error` event listener in [`replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/replace.ts) when external assets fail to load.
- **Uncaught JavaScript exceptions** are intercepted through the same `error` event mechanism, extracting line numbers and stack traces automatically.
- **Unhandled Promise rejections** trigger the `unhandledrejection` listener, ensuring async failures are recorded even without explicit error boundaries.
- **Console error calls** are wrapped via `replaceConsoleError`, converting developer-logged messages into trackable error events.
- **Default behavior** has error collection disabled (`core: false`, `server: false`) and requires explicit activation through `initOptions`.

## Frequently Asked Questions

### Does web-tracing capture errors automatically without configuration?

No. According to the [`options.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/options.ts) source file, web-tracing initializes with `error.core` and `error.server` set to `false` by default. You must explicitly set `error.core: true` in the `initOptions` configuration to activate the global event listeners and console wrappers that capture the four error types.

### Which source file contains the error capture implementation?

The primary implementation resides in [`packages/core/src/lib/replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/replace.ts). This file exports three key functions: `listenError` (handling resource and JS errors), `listenUnhandledrejection` (handling Promise rejections), and `replaceConsoleError` (instrumenting console methods).

### How does web-tracing differentiate between error types in the reporting payload?

Each error handler in [`replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/replace.ts) tags events with specific metadata before pushing them to the event bus. Resource errors include the failed URL and element tag name, JS exceptions include stack traces and line numbers, Promise rejections include the rejection reason object, and console errors include the logged arguments array.

### Can I capture errors in web workers or service workers?

The analysis focuses on main-thread execution. While the current [`replace.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/replace.ts) implementation attaches to `window` events for browser contexts, web-tracing's modular architecture in `packages/core` suggests that worker environments would require separate instrumentation following similar patterns for `onerror` and `onunhandledrejection` handlers within the worker scope.