0
# Extra Error Data
1

2
Extracts additional custom properties from Error objects and attaches them as event context. This integration captures non-standard error properties, error causes, and custom data attached to Error instances.
3

4
## Capabilities
5

6
### Modern Function-based Integration
7

8
```typescript { .api }
9
/**
10
 * Extracts additional data from original exceptions
11
 * @param options - Configuration for error data extraction
12
 * @returns Integration instance that enhances error events
13
 */
14
function extraErrorDataIntegration(options?: Partial<ExtraErrorDataOptions>): Integration;
15

16
interface ExtraErrorDataOptions {
17
  /** The object depth up to which to capture data on error objects. Default: 3 */
18
  depth: number;
19
  /** Whether to capture error causes (Error.cause property). Default: false */
20
  captureErrorCause: boolean;
21
}
22
```
23

24
### Legacy Class-based Integration (Deprecated)
25

26
```typescript { .api }
27
/**
28
 * Legacy class-based extra error data integration
29
 * @deprecated Use extraErrorDataIntegration() instead
30
 */
31
class ExtraErrorData implements Integration {
32
  constructor(options?: Partial<{
33
    depth: number;
34
    captureErrorCause: boolean;
35
  }>);
36
  name: string;
37
  processEvent(event: Event, hint: EventHint): Event;
38
}
39
```
40

41
## Configuration Options
42

43
### depth Option
44

45
Controls how deeply nested objects on Error instances are serialized:
46
- **Default**: 3 levels deep
47
- **Purpose**: Prevents infinite recursion and excessive data capture
48
- **Applied**: Uses `normalize()` from @sentry/utils with specified depth
49

50
### captureErrorCause Option
51

52
Controls whether to capture the standard `Error.cause` property:
53
- **Default**: false (will be true in v8)
54
- **Standard**: Part of ES2022 Error.cause specification
55
- **Fallback**: Non-enumerable property access for `error.cause`
56

57
## Behavior
58

59
### Property Extraction
60

61
The integration extracts all enumerable properties from Error objects, excluding standard Error properties:
62

63
**Excluded Properties** (native Error properties):
64
- `name`, `message`, `stack`
65
- `line`, `column`, `fileName`
66
- `lineNumber`, `columnNumber`
67
- `toJSON`
68

69
**Additional Processing**:
70
- Error values in custom properties are converted to strings
71
- `toJSON()` method results are merged if present
72
- `Error.cause` captured separately when enabled
73

74
### Context Attachment
75

76
Extracted data is attached to the event under `contexts[ExceptionName]`:
77
- Context key uses the Error constructor name or `name` property
78
- Data is normalized to prevent serialization issues
79
- Marked with `__sentry_skip_normalization__` to prevent double-processing
80

81
## Usage Examples
82

83
```typescript
84
import { extraErrorDataIntegration } from '@sentry/integrations';
85
import * as Sentry from '@sentry/browser';
86

87
// Basic setup with defaults
88
Sentry.init({
89
  dsn: 'YOUR_DSN',
90
  integrations: [
91
    extraErrorDataIntegration()
92
  ]
93
});
94

95
// Custom configuration
96
Sentry.init({
97
  dsn: 'YOUR_DSN',
98
  integrations: [
99
    extraErrorDataIntegration({
100
      depth: 5,              // Deeper object traversal
101
      captureErrorCause: true // Include error causes
102
    })
103
  ]
104
});
105

106
// Usage with custom error properties
107
class CustomError extends Error {
108
  constructor(message, { userId, requestId, metadata }) {
109
    super(message);
110
    this.userId = userId;
111
    this.requestId = requestId;
112
    this.metadata = metadata;
113
    this.timestamp = Date.now();
114
  }
115
}
116

117
// Error with cause chain
118
const rootCause = new Error('Database connection failed');
119
const apiError = new Error('API request failed', { cause: rootCause });
120
apiError.statusCode = 500;
121
apiError.endpoint = '/api/users';
122

123
throw apiError;
124
// Results in Sentry event with custom properties in contexts
125
```
126

127
## Error Object Examples
128

129
### Custom Error Properties
130

131
```javascript
132
const error = new Error('Custom error');
133
error.userId = '12345';
134
error.context = { 
135
  action: 'data-processing',
136
  retryCount: 3 
137
};
138
error.timestamp = Date.now();
139

140
throw error;
141
// Custom properties appear in Sentry contexts
142
```
143

144
### Library Error Objects
145

146
Many libraries attach additional data to errors:
147

148
```javascript
149
// Axios errors
150
const axiosError = new Error('Request failed');
151
axiosError.config = { url: '/api', method: 'POST' };
152
axiosError.response = { status: 404, data: { error: 'Not found' } };
153

154
// This data is automatically captured
155
throw axiosError;
156
```
157

158
### Error Causes (ES2022)
159

160
```javascript
161
const dbError = new Error('Connection timeout');
162
const serviceError = new Error('Service unavailable', { cause: dbError });
163

164
// Both error messages and cause chain captured when enabled
165
throw serviceError;
166
```
167

168
The integration is particularly valuable for applications using custom Error classes or third-party libraries that attach metadata to Error objects.