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

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. 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【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 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. 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.

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, 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:

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 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 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 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. 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}