0
# Error Handling & Processing
1

2
**DEPRECATED**: Import all functions from `@sentry/core` instead of `@sentry/utils`.
3

4
Core error processing functionality for detecting, normalizing, and enriching error data before transmission to Sentry.
5

6
## Capabilities
7

8
### SentryError Class
9

10
Custom error class for Sentry-specific errors with optional log level.
11

12
```typescript { .api }
13
/**
14
 * Custom error class for Sentry-specific errors
15
 */
16
class SentryError extends Error {
17
  /** Log level for the error */
18
  logLevel?: string;
19
  
20
  /**
21
   * Creates a new SentryError
22
   * @param message - Error message
23
   * @param logLevel - Optional log level (default: 'error')
24
   */
25
  constructor(message: string, logLevel?: string);
26
}
27
```
28

29
**Usage Example:**
30

31
```typescript
32
import { SentryError } from "@sentry/core"; // ✅ Recommended (was @sentry/utils)
33

34
const error = new SentryError("Configuration is invalid", "warn");
35
throw error;
36
```
37

38
### Error Type Guards
39

40
Type guard functions for safe error type detection.
41

42
```typescript { .api }
43
/**
44
 * Type guard for Error objects
45
 * @param wat - Value to check
46
 * @returns True if value is an Error
47
 */
48
function isError(wat: unknown): wat is Error;
49

50
/**
51
 * Type guard for ErrorEvent objects (browser events)
52
 * @param wat - Value to check  
53
 * @returns True if value is an ErrorEvent
54
 */
55
function isErrorEvent(wat: unknown): wat is ErrorEvent;
56

57
/**
58
 * Type guard for DOMError objects
59
 * @param wat - Value to check
60
 * @returns True if value is a DOMError
61
 */
62
function isDOMError(wat: unknown): wat is DOMError;
63

64
/**
65
 * Type guard for DOMException objects
66
 * @param wat - Value to check
67
 * @returns True if value is a DOMException  
68
 */
69
function isDOMException(wat: unknown): wat is DOMException;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { isError, isErrorEvent, isDOMError } from "@sentry/core";
76

77
function handleUnknownError(error: unknown) {
78
  if (isError(error)) {
79
    console.log("Standard Error:", error.message);
80
  } else if (isErrorEvent(error)) {
81
    console.log("Error Event:", error.error?.message);
82
  } else if (isDOMError(error)) {
83
    console.log("DOM Error:", error.name);
84
  }
85
}
86
```
87

88
### Exception Processing
89

90
Functions for converting errors into Sentry exception format.
91

92
```typescript { .api }
93
interface Exception {
94
  type?: string;
95
  value?: string;
96
  mechanism?: Mechanism;
97
  module?: string;
98
  thread_id?: number;
99
  stacktrace?: Stacktrace;
100
}
101

102
interface Mechanism {
103
  type: string;
104
  description?: string;
105
  help_link?: string;
106
  handled?: boolean;
107
  synthetic?: boolean;
108
  data?: { [key: string]: string | boolean };
109
}
110

111
interface Stacktrace {
112
  frames?: StackFrame[];
113
  frames_omitted?: [number, number];
114
}
115

116
/**
117
 * Converts an Error object into a Sentry Exception format
118
 * @param parser - Stack parser to use for parsing stack trace
119
 * @param ex - Error object to convert
120
 * @returns Exception object suitable for Sentry
121
 */
122
function exceptionFromError(parser: StackParser, ex: Error): Exception;
123

124
/**
125
 * Extracts exception keys for message generation
126
 * @param ex - Exception object
127
 * @returns String representation of exception keys
128
 */
129
function extractExceptionKeysForMessage(ex: Exception): string;
130
```
131

132
### Exception Enrichment
133

134
Functions for adding metadata and context to exceptions.
135

136
```typescript { .api }
137
/**
138
 * Adds exception mechanism information to an event
139
 * @param event - Event to modify
140
 * @param mechanism - Mechanism data to add
141
 */
142
function addExceptionMechanism(
143
  event: Event,
144
  mechanism: Partial<Mechanism>
145
): void;
146

147
/**
148
 * Adds exception type and value to an event
149
 * @param event - Event to modify
150
 * @param value - Exception message/value
151
 * @param type - Exception type/name
152
 */
153
function addExceptionTypeValue(
154
  event: Event,
155
  value?: string,
156
  type?: string
157
): void;
158

159
/**
160
 * Checks or sets the already caught flag on an exception
161
 * @param exception - Exception to check/modify
162
 * @returns True if exception was already caught
163
 */
164
function checkOrSetAlreadyCaught(exception: Exception): boolean;
165
```
166

167
### Aggregate Error Processing
168

169
Handles errors that contain multiple nested errors (AggregateError, Promise.allSettled rejections).
170

171
```typescript { .api }
172
/**
173
 * Applies aggregate errors to an event, extracting nested errors
174
 * @param exceptionFromErrorImplementation - Function to convert errors to exceptions
175
 * @param parser - Stack parser instance
176
 * @param maxValueLimit - Maximum depth for value extraction
177
 * @param key - Key name for the aggregate error
178
 * @param limit - Maximum number of nested errors to process
179
 * @param event - Event to modify
180
 * @param hint - Optional event hint for additional context
181
 */
182
function applyAggregateErrorsToEvent(
183
  exceptionFromErrorImplementation: (stackParser: StackParser, ex: Error) => Exception,
184
  parser: StackParser,
185
  maxValueLimit: number,
186
  key: string,
187
  limit: number,
188
  event: Event,
189
  hint?: EventHint,
190
): void;
191
```
192

193
**Usage Example:**
194

195
```typescript
196
import { 
197
  exceptionFromError, 
198
  addExceptionMechanism, 
199
  createStackParser,
200
  nodeStackLineParser 
201
} from "@sentry/core";
202

203
const parser = createStackParser(nodeStackLineParser());
204

205
try {
206
  // Some operation that might fail
207
  throw new Error("Something went wrong");
208
} catch (error) {
209
  if (isError(error)) {
210
    const exception = exceptionFromError(parser, error);
211
    
212
    const event = {
213
      exception: {
214
        values: [exception]
215
      }
216
    };
217
    
218
    // Add mechanism information
219
    addExceptionMechanism(event, {
220
      type: "generic",
221
      handled: true
222
    });
223
  }
224
}
225
```
226

227
## Error Processing Workflow
228

229
1. **Detection**: Use type guards (`isError`, `isErrorEvent`, etc.) to identify error types
230
2. **Conversion**: Convert errors to Sentry exception format with `exceptionFromError`  
231
3. **Enrichment**: Add mechanism data, context, and metadata
232
4. **Aggregation**: Handle nested errors with `applyAggregateErrorsToEvent`
233
5. **Transmission**: Package in envelope format for sending to Sentry
234

235
**Migration Note**: All error handling functions have been moved from `@sentry/utils` to `@sentry/core`. Update your imports accordingly.