0
# Error Processing
1

2
Advanced error processing utilities for server-side error handling, stack frame analysis, and comprehensive error formatting with source map integration.
3

4
## Capabilities
5

6
### Error Processing by Type
7

8
Process and format different types of errors with comprehensive stack trace analysis and source mapping.
9

10
```typescript { .api }
11
/**
12
 * Processes and formats errors by type, returning structured error objects
13
 * @param ev - Error event with ID and event data
14
 * @returns Promise resolving to formatted runtime error with frames
15
 */
16
function getErrorByType(ev: SupportedErrorEvent): Promise<ReadyRuntimeError>;
17

18
interface SupportedErrorEvent {
19
  id: number;
20
  event: BusEvent;
21
}
22

23
interface ReadyRuntimeError {
24
  id: number;
25
  runtime: true;
26
  error: Error;
27
  frames: OriginalStackFrame[];
28
  componentStack?: string[];
29
}
30

31
interface BusEvent {
32
  type: string;
33
  reason?: Error;
34
  message?: string;
35
  frames?: StackFrame[];
36
  componentStack?: string[];
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { getErrorByType } from "@next/react-dev-overlay";
44

45
// Process error event
46
async function handleErrorEvent(errorEvent: SupportedErrorEvent) {
47
  try {
48
    const processedError = await getErrorByType(errorEvent);
49
    
50
    console.log('Error ID:', processedError.id);
51
    console.log('Original error:', processedError.error.message);
52
    console.log('Stack frames:', processedError.frames.length);
53
    
54
    if (processedError.componentStack) {
55
      console.log('React component stack:', processedError.componentStack);
56
    }
57
    
58
    return processedError;
59
  } catch (error) {
60
    console.error('Failed to process error:', error);
61
  }
62
}
63

64
// Create error event
65
const errorEvent: SupportedErrorEvent = {
66
  id: Date.now(),
67
  event: {
68
    type: 'unhandled-error',
69
    reason: new Error('Something went wrong'),
70
    frames: [], // Parsed stack frames
71
  }
72
};
73

74
const processedError = await getErrorByType(errorEvent);
75
```
76

77
### Original Stack Frame Processing
78

79
Process individual stack frames and arrays of stack frames with source mapping and error context.
80

81
```typescript { .api }
82
/**
83
 * Processes individual stack frames with source mapping
84
 * @param source - Original stack frame from error
85
 * @param type - Type of server context for processing
86
 * @param errorMessage - Error message for context
87
 * @returns Promise resolving to processed original stack frame
88
 */
89
function getOriginalStackFrame(
90
  source: StackFrame,
91
  type: 'server' | 'edge-server' | null,
92
  errorMessage: string
93
): Promise<OriginalStackFrame>;
94

95
/**
96
 * Processes array of stack frames with source mapping
97
 * @param frames - Array of stack frames to process
98
 * @param type - Type of server context for processing  
99
 * @param errorMessage - Error message for context
100
 * @returns Promise resolving to array of processed frames
101
 */
102
function getOriginalStackFrames(
103
  frames: StackFrame[],
104
  type: 'server' | 'edge-server' | null,
105
  errorMessage: string
106
): Promise<OriginalStackFrame[]>;
107

108
/**
109
 * Extracts source information from stack frames
110
 * @param frame - Stack frame to extract source from
111
 * @returns Source information string
112
 */
113
function getFrameSource(frame: StackFrame): string;
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
import { 
120
  getOriginalStackFrame, 
121
  getOriginalStackFrames, 
122
  getFrameSource 
123
} from "@next/react-dev-overlay";
124

125
// Process single stack frame
126
async function processSingleFrame(frame: StackFrame) {
127
  const originalFrame = await getOriginalStackFrame(
128
    frame,
129
    'server',
130
    'Database connection failed'
131
  );
132
  
133
  console.log('Processed frame:', originalFrame);
134
  return originalFrame;
135
}
136

137
// Process multiple stack frames
138
async function processAllFrames(frames: StackFrame[]) {
139
  const originalFrames = await getOriginalStackFrames(
140
    frames,
141
    null,
142
    'Client-side error occurred'
143
  );
144
  
145
  originalFrames.forEach((frame, index) => {
146
    console.log(`Frame ${index}:`, frame);
147
  });
148
  
149
  return originalFrames;
150
}
151

152
// Extract source information
153
function analyzeFrame(frame: StackFrame) {
154
  const source = getFrameSource(frame);
155
  console.log('Frame source:', source);
156
  return source;
157
}
158
```
159

160
### Server Error Processing
161

162
Create and process server-specific errors with enhanced context and stack trace information.
163

164
```typescript { .api }
165
/**
166
 * Converts stack frames to filesystem paths
167
 * @param frame - Stack frame to convert
168
 * @returns Stack frame with filesystem path
169
 */
170
function getFilesystemFrame(frame: StackFrame): StackFrame;
171

172
/**
173
 * Determines error source context from error object
174
 * @param error - Error object to analyze
175
 * @returns Error source type or null
176
 */
177
function getErrorSource(error: Error): 'server' | 'edge-server' | null;
178

179
/**
180
 * Decorates errors with server context information
181
 * @param error - Error object to decorate
182
 * @param type - Type of server context to add
183
 */
184
function decorateServerError(error: Error, type: ErrorType): void;
185

186
/**
187
 * Creates server errors with proper stack traces and context
188
 * @param error - Original error object
189
 * @param type - Type of error context
190
 * @returns Enhanced error object with server context
191
 */
192
function getServerError(error: Error, type: ErrorType): Error;
193

194
type ErrorType = 'server' | 'edge-server';
195
```
196

197
**Usage Examples:**
198

199
```typescript
200
import { 
201
  getFilesystemFrame,
202
  getErrorSource,
203
  decorateServerError,
204
  getServerError 
205
} from "@next/react-dev-overlay";
206

207
// Convert to filesystem frame
208
function convertToFilesystem(frame: StackFrame) {
209
  const filesystemFrame = getFilesystemFrame(frame);
210
  console.log('Filesystem path:', filesystemFrame.file);
211
  return filesystemFrame;
212
}
213

214
// Analyze error source
215
function analyzeErrorSource(error: Error) {
216
  const source = getErrorSource(error);
217
  
218
  switch (source) {
219
    case 'server':
220
      console.log('Server-side error detected');
221
      break;
222
    case 'edge-server':
223
      console.log('Edge server error detected');
224
      break;
225
    default:
226
      console.log('Client-side or unknown error');
227
  }
228
  
229
  return source;
230
}
231

232
// Decorate server error
233
function enhanceServerError(error: Error) {
234
  decorateServerError(error, 'server');
235
  // Error object is now enhanced with server context
236
  throw error;
237
}
238

239
// Create enhanced server error
240
function createServerError(originalError: Error) {
241
  const serverError = getServerError(originalError, 'server');
242
  console.log('Enhanced server error:', serverError);
243
  return serverError;
244
}
245
```
246

247
### Stack Parsing and Analysis
248

249
Parse JavaScript stack traces into structured format with comprehensive analysis.
250

251
```typescript { .api }
252
/**
253
 * Parses error stack traces into structured StackFrame objects
254
 * @param stack - Raw stack trace string from error
255
 * @returns Array of parsed and structured stack frames
256
 */
257
function parseStack(stack: string): StackFrame[];
258

259
interface StackFrame {
260
  file: string | null;
261
  methodName: string | null;
262
  arguments: string[];
263
  lineNumber: number | null;
264
  column: number | null;
265
}
266
```
267

268
**Usage Examples:**
269

270
```typescript
271
import { parseStack } from "@next/react-dev-overlay";
272

273
// Parse error stack trace
274
function analyzeErrorStack(error: Error) {
275
  if (!error.stack) {
276
    console.log('No stack trace available');
277
    return [];
278
  }
279
  
280
  const frames = parseStack(error.stack);
281
  
282
  console.log(`Parsed ${frames.length} stack frames:`);
283
  frames.forEach((frame, index) => {
284
    console.log(`  ${index + 1}. ${frame.methodName || '<anonymous>'}`);
285
    console.log(`     File: ${frame.file || 'unknown'}`);
286
    console.log(`     Line: ${frame.lineNumber || 'unknown'}`);
287
    console.log(`     Column: ${frame.column || 'unknown'}`);
288
  });
289
  
290
  return frames;
291
}
292

293
// Filter relevant frames
294
function getAppFrames(error: Error): StackFrame[] {
295
  const allFrames = parseStack(error.stack || '');
296
  
297
  // Filter out node_modules and system frames
298
  return allFrames.filter(frame => {
299
    if (!frame.file) return false;
300
    if (frame.file.includes('node_modules')) return false;
301
    if (frame.file.includes('/internal/')) return false;
302
    return true;
303
  });
304
}
305

306
// Find error origin
307
function findErrorOrigin(error: Error): StackFrame | null {
308
  const frames = parseStack(error.stack || '');
309
  
310
  // Find first frame that's in application code
311
  return frames.find(frame => 
312
    frame.file && 
313
    !frame.file.includes('node_modules') &&
314
    frame.lineNumber !== null
315
  ) || null;
316
}
317
```
318

319
## Stack Frame Types
320

321
Comprehensive type definitions for different stack frame states and error processing.
322

323
```typescript { .api }
324
type OriginalStackFrame = 
325
  | OriginalStackFrameError 
326
  | OriginalStackFrameExternal 
327
  | OriginalStackFrameInternal;
328

329
interface OriginalStackFrameError {
330
  error: true;
331
  reason: string;
332
  external: false;
333
  expanded: false;
334
  sourceStackFrame: StackFrame;
335
}
336

337
interface OriginalStackFrameExternal {
338
  error: false;
339
  external: true;
340
  expanded: boolean;
341
  sourceStackFrame: StackFrame;
342
}
343

344
interface OriginalStackFrameInternal {
345
  error: false;
346
  reason: null;
347
  external: false;
348
  expanded: boolean;
349
  sourceStackFrame: StackFrame;
350
  originalCodeFrame: string | null;
351
  originalStackFrame: StackFrame;
352
}
353
```
354

355
## Error Processing Workflow
356

357
Complete workflow for processing errors from capture to display:
358

359
```typescript
360
// Complete error processing workflow
361
async function processError(error: Error): Promise<ReadyRuntimeError> {
362
  // 1. Parse stack trace
363
  const frames = parseStack(error.stack || '');
364
  
365
  // 2. Determine error source
366
  const source = getErrorSource(error);
367
  
368
  // 3. Process each frame
369
  const originalFrames = await getOriginalStackFrames(
370
    frames,
371
    source,
372
    error.message
373
  );
374
  
375
  // 4. Create processed error
376
  const processedError: ReadyRuntimeError = {
377
    id: Date.now(),
378
    runtime: true,
379
    error: error,
380
    frames: originalFrames,
381
  };
382
  
383
  return processedError;
384
}
385
```