Error Handling

Vestig provides robust utilities for handling and logging errors safely. These utilities support ES2022 error cause chains, extract common error properties, and prevent sensitive information from leaking into logs.

Overview

When logging errors in production, you need to:

Serialize safely - Avoid circular references and non-serializable data
Preserve context - Keep error names, messages, and stack traces
Handle cause chains - Support ES2022 cause property
Extract metadata - Capture code, statusCode, and system error properties

Vestig handles all of this automatically when you pass errors to log methods.

Basic Error Logging

typescript

1import { log } from 'vestig'
2 
3try {
4  await riskyOperation()
5} catch (error) {
6  // Pass error directly - Vestig serializes it safely
7  log.error('Operation failed', { error })
8}

Output:

json

1{
2  "level": "error",
3  "message": "Operation failed",
4  "error": {
5    "name": "Error",
6    "message": "Connection timeout",
7    "stack": "Error: Connection timeout\n    at riskyOperation..."
8  }
9}

Error Utilities

serializeError

Convert any error to a safe, serializable format:

typescript

1import { serializeError } from 'vestig'
2 
3const error = new Error('Something went wrong')
4const serialized = serializeError(error)
5 
6console.log(serialized)
7// {
8//   name: 'Error',
9//   message: 'Something went wrong',
10//   stack: 'Error: Something went wrong\n    at ...'
11// }

Handles many input types:

typescript

1// Error instances
2serializeError(new TypeError('Invalid type'))
3// { name: 'TypeError', message: 'Invalid type', stack: '...' }
4 
5// Error-like objects
6serializeError({ message: 'Custom error', name: 'CustomError' })
7// { name: 'CustomError', message: 'Custom error' }
8 
9// Strings (converted to Error)
10serializeError('Simple error string')
11// { name: 'Error', message: 'Simple error string' }
12 
13// Returns undefined for non-errors
14serializeError(null)      // undefined
15serializeError(123)       // undefined
16serializeError({})        // undefined (no message property)

isError

Check if a value is an Error or error-like object:

typescript

1import { isError } from 'vestig'
2 
3isError(new Error('test'))           // true
4isError(new TypeError('test'))       // true
5isError({ message: 'error' })        // true (error-like object)
6 
7isError(null)                        // false
8isError('error string')              // false
9isError({ name: 'Error' })           // false (no message)

getErrorMessage

Extract the error message from any value:

typescript

1import { getErrorMessage } from 'vestig'
2 
3getErrorMessage(new Error('test'))     // 'test'
4getErrorMessage('string error')        // 'string error'
5getErrorMessage({ message: 'error' })  // 'error'
6getErrorMessage(123)                   // '123'
7getErrorMessage(null)                  // 'null'

Error Cause Chains (ES2022)

Vestig fully supports ES2022 error cause chains:

typescript

1import { serializeError, log } from 'vestig'
2 
3// Create error with cause chain
4try {
5  await fetchUser()
6} catch (fetchError) {
7  const error = new Error('Failed to load user profile', {
8    cause: fetchError
9  })
10 
11  log.error('Profile load failed', { error })
12}

The cause chain is preserved in serialization:

json

1{
2  "level": "error",
3  "message": "Profile load failed",
4  "error": {
5    "name": "Error",
6    "message": "Failed to load user profile",
7    "stack": "Error: Failed to load user profile\n    at ...",
8    "cause": {
9      "name": "FetchError",
10      "message": "Network request failed",
11      "stack": "FetchError: Network request failed\n    at ...",
12      "cause": {
13        "name": "Error",
14        "message": "ECONNREFUSED",
15        "code": "ECONNREFUSED"
16      }
17    }
18  }
19}

Nested Cause Chains

typescript

1const rootCause = new Error('Database connection lost')
2const dbError = new Error('Query execution failed', { cause: rootCause })
3const serviceError = new Error('User service unavailable', { cause: dbError })
4 
5const serialized = serializeError(serviceError)
6 
7// Entire chain is preserved
8console.log(serialized.message)              // 'User service unavailable'
9console.log(serialized.cause.message)        // 'Query execution failed'
10console.log(serialized.cause.cause.message)  // 'Database connection lost'

Depth Limit

To prevent infinite loops with circular references, cause chains are limited to 10 levels:

typescript

1// Creating a deeply nested error (for demonstration)
2let error = new Error('level 0')
3for (let i = 1; i <= 15; i++) {
4  error = new Error(`level ${i}`, { cause: error })
5}
6 
7const serialized = serializeError(error)
8// Serialization stops at depth 10, preventing infinite recursion

System Error Properties

Vestig automatically extracts common error properties:

typescript

1// Node.js file system error
2const fsError = new Error('ENOENT: no such file or directory') as Error & {
3  code: string
4  errno: number
5  syscall: string
6  path: string
7}
8fsError.code = 'ENOENT'
9fsError.errno = -2
10fsError.syscall = 'open'
11fsError.path = '/missing/file.txt'
12 
13log.error('File operation failed', { error: fsError })

Output:

json

1{
2  "level": "error",
3  "message": "File operation failed",
4  "error": {
5    "name": "Error",
6    "message": "ENOENT: no such file or directory",
7    "stack": "...",
8    "code": "ENOENT",
9    "errno": -2,
10    "syscall": "open",
11    "path": "/missing/file.txt"
12  }
13}

Extracted Properties

Property	Type	Description
`code`	`string \| number`	Error code (e.g., 'ENOENT', 'ETIMEDOUT')
`statusCode`	`number`	HTTP status code
`status`	`number`	Alternative HTTP status
`errno`	`number`	System error number
`syscall`	`string`	System call that failed
`path`	`string`	File path for FS errors
`address`	`string`	Network address
`port`	`number`	Network port

HTTP Error Handling

typescript

1class HttpError extends Error {
2  constructor(
3    message: string,
4    public statusCode: number,
5    public code: string
6  ) {
7    super(message)
8    this.name = 'HttpError'
9  }
10}
11 
12try {
13  throw new HttpError('User not found', 404, 'USER_NOT_FOUND')
14} catch (error) {
15  log.warn('Request failed', { error })
16}

Output:

json

1{
2  "level": "warn",
3  "message": "Request failed",
4  "error": {
5    "name": "HttpError",
6    "message": "User not found",
7    "statusCode": 404,
8    "code": "USER_NOT_FOUND"
9  }
10}

Error Boundaries (React)

With @vestig/next, use the error boundary component:

tsx

1import { VestigErrorBoundary } from '@vestig/next/client'
2 
3function App() {
4  return (
5    <VestigErrorBoundary
6      fallback={<ErrorFallback />}
7      onError={(error, errorInfo) => {
8        // Error is automatically logged with component stack
9      }}
10    >
11      <MyComponent />
12    </VestigErrorBoundary>
13  )
14}

Best Practices

1. Always Wrap Unknown Errors

typescript

1try {
2  await externalLibrary.doSomething()
3} catch (unknownError) {
4  // Wrap with context
5  const error = new Error('External operation failed', {
6    cause: unknownError
7  })
8  log.error('Operation failed', { error })
9}

2. Use Appropriate Log Levels

typescript

1// Expected errors (business logic) → warn
2log.warn('User not found', { error, userId })
3 
4// Unexpected errors (bugs, system failures) → error
5log.error('Database connection failed', { error })
6 
7// Fatal errors (app can't continue) → error with context
8log.error('Failed to initialize', { error, fatal: true })

3. Include Context

typescript

1try {
2  await processOrder(orderId)
3} catch (error) {
4  log.error('Order processing failed', {
5    error,
6    orderId,
7    userId: ctx.userId,
8    action: 'process_order',
9  })
10}

4. Handle Rejected Promises

typescript

1// Option 1: Try/catch with async/await
2async function handler() {
3  try {
4    await riskyOperation()
5  } catch (error) {
6    log.error('Operation failed', { error })
7  }
8}
9 
10// Option 2: Promise .catch()
11riskyOperation()
12  .catch(error => log.error('Operation failed', { error }))
13 
14// Option 3: Global unhandled rejection handler
15process.on('unhandledRejection', (reason) => {
16  log.error('Unhandled promise rejection', {
17    error: reason
18  })
19})

5. Don't Log Sensitive Data

typescript

1// ❌ Bad: May include passwords, tokens
2log.error('Auth failed', { error, credentials })
3 
4// ✅ Good: Log only safe metadata
5log.error('Auth failed', {
6  error,
7  username: credentials.username,
8  // Don't include password
9})

API Reference

Types

typescript

1interface SerializedError {
2  name: string
3  message: string
4  stack?: string
5  cause?: SerializedError
6  code?: string | number
7  statusCode?: number
8  status?: number
9  errno?: number
10  syscall?: string
11  path?: string
12  address?: string
13  port?: number
14  [key: string]: unknown
15}

Functions

Function	Description
`serializeError(error, depth?)`	Serialize error with cause chain
`isError(value)`	Check if value is error-like
`getErrorMessage(error)`	Extract message from any value

Integration with Transports

All Vestig transports receive serialized errors:

typescript

1import { createLogger, ConsoleTransport, HTTPTransport } from 'vestig'
2 
3const logger = createLogger({
4  transports: [
5    new ConsoleTransport(), // Pretty-prints errors with colors
6    new HTTPTransport({
7      endpoint: '/api/logs'  // Sends serialized error JSON
8    })
9  ]
10})
11 
12// Errors are automatically serialized for all transports
13logger.error('Critical failure', { error: new Error('Something broke') })

Error Handling

Overview

When logging errors in production, you need to:

Serialize safely - Avoid circular references and non-serializable data
Preserve context - Keep error names, messages, and stack traces
Handle cause chains - Support ES2022 cause property
Extract metadata - Capture code, statusCode, and system error properties

Vestig handles all of this automatically when you pass errors to log methods.

Basic Error Logging

typescript

1import { log } from 'vestig'
2 
3try {
4  await riskyOperation()
5} catch (error) {
6  // Pass error directly - Vestig serializes it safely
7  log.error('Operation failed', { error })
8}

Output:

json

1{
2  "level": "error",
3  "message": "Operation failed",
4  "error": {
5    "name": "Error",
6    "message": "Connection timeout",
7    "stack": "Error: Connection timeout\n    at riskyOperation..."
8  }
9}

Error Utilities

serializeError

Convert any error to a safe, serializable format:

typescript

1import { serializeError } from 'vestig'
2 
3const error = new Error('Something went wrong')
4const serialized = serializeError(error)
5 
6console.log(serialized)
7// {
8//   name: 'Error',
9//   message: 'Something went wrong',
10//   stack: 'Error: Something went wrong\n    at ...'
11// }

Handles many input types:

typescript

1// Error instances
2serializeError(new TypeError('Invalid type'))
3// { name: 'TypeError', message: 'Invalid type', stack: '...' }
4 
5// Error-like objects
6serializeError({ message: 'Custom error', name: 'CustomError' })
7// { name: 'CustomError', message: 'Custom error' }
8 
9// Strings (converted to Error)
10serializeError('Simple error string')
11// { name: 'Error', message: 'Simple error string' }
12 
13// Returns undefined for non-errors
14serializeError(null)      // undefined
15serializeError(123)       // undefined
16serializeError({})        // undefined (no message property)

isError

Check if a value is an Error or error-like object:

typescript

1import { isError } from 'vestig'
2 
3isError(new Error('test'))           // true
4isError(new TypeError('test'))       // true
5isError({ message: 'error' })        // true (error-like object)
6 
7isError(null)                        // false
8isError('error string')              // false
9isError({ name: 'Error' })           // false (no message)

getErrorMessage

Extract the error message from any value:

typescript

1import { getErrorMessage } from 'vestig'
2 
3getErrorMessage(new Error('test'))     // 'test'
4getErrorMessage('string error')        // 'string error'
5getErrorMessage({ message: 'error' })  // 'error'
6getErrorMessage(123)                   // '123'
7getErrorMessage(null)                  // 'null'

Error Cause Chains (ES2022)

Vestig fully supports ES2022 error cause chains:

typescript

1import { serializeError, log } from 'vestig'
2 
3// Create error with cause chain
4try {
5  await fetchUser()
6} catch (fetchError) {
7  const error = new Error('Failed to load user profile', {
8    cause: fetchError
9  })
10 
11  log.error('Profile load failed', { error })
12}

The cause chain is preserved in serialization:

json

1{
2  "level": "error",
3  "message": "Profile load failed",
4  "error": {
5    "name": "Error",
6    "message": "Failed to load user profile",
7    "stack": "Error: Failed to load user profile\n    at ...",
8    "cause": {
9      "name": "FetchError",
10      "message": "Network request failed",
11      "stack": "FetchError: Network request failed\n    at ...",
12      "cause": {
13        "name": "Error",
14        "message": "ECONNREFUSED",
15        "code": "ECONNREFUSED"
16      }
17    }
18  }
19}

Nested Cause Chains

typescript

1const rootCause = new Error('Database connection lost')
2const dbError = new Error('Query execution failed', { cause: rootCause })
3const serviceError = new Error('User service unavailable', { cause: dbError })
4 
5const serialized = serializeError(serviceError)
6 
7// Entire chain is preserved
8console.log(serialized.message)              // 'User service unavailable'
9console.log(serialized.cause.message)        // 'Query execution failed'
10console.log(serialized.cause.cause.message)  // 'Database connection lost'

Depth Limit

To prevent infinite loops with circular references, cause chains are limited to 10 levels:

typescript

1// Creating a deeply nested error (for demonstration)
2let error = new Error('level 0')
3for (let i = 1; i <= 15; i++) {
4  error = new Error(`level ${i}`, { cause: error })
5}
6 
7const serialized = serializeError(error)
8// Serialization stops at depth 10, preventing infinite recursion

System Error Properties

Vestig automatically extracts common error properties:

typescript

1// Node.js file system error
2const fsError = new Error('ENOENT: no such file or directory') as Error & {
3  code: string
4  errno: number
5  syscall: string
6  path: string
7}
8fsError.code = 'ENOENT'
9fsError.errno = -2
10fsError.syscall = 'open'
11fsError.path = '/missing/file.txt'
12 
13log.error('File operation failed', { error: fsError })

Output:

json

1{
2  "level": "error",
3  "message": "File operation failed",
4  "error": {
5    "name": "Error",
6    "message": "ENOENT: no such file or directory",
7    "stack": "...",
8    "code": "ENOENT",
9    "errno": -2,
10    "syscall": "open",
11    "path": "/missing/file.txt"
12  }
13}

Extracted Properties

Property	Type	Description
`code`	`string \| number`	Error code (e.g., 'ENOENT', 'ETIMEDOUT')
`statusCode`	`number`	HTTP status code
`status`	`number`	Alternative HTTP status
`errno`	`number`	System error number
`syscall`	`string`	System call that failed
`path`	`string`	File path for FS errors
`address`	`string`	Network address
`port`	`number`	Network port

HTTP Error Handling

typescript

1class HttpError extends Error {
2  constructor(
3    message: string,
4    public statusCode: number,
5    public code: string
6  ) {
7    super(message)
8    this.name = 'HttpError'
9  }
10}
11 
12try {
13  throw new HttpError('User not found', 404, 'USER_NOT_FOUND')
14} catch (error) {
15  log.warn('Request failed', { error })
16}

Output:

json

1{
2  "level": "warn",
3  "message": "Request failed",
4  "error": {
5    "name": "HttpError",
6    "message": "User not found",
7    "statusCode": 404,
8    "code": "USER_NOT_FOUND"
9  }
10}

Error Boundaries (React)

With @vestig/next, use the error boundary component:

tsx

1import { VestigErrorBoundary } from '@vestig/next/client'
2 
3function App() {
4  return (
5    <VestigErrorBoundary
6      fallback={<ErrorFallback />}
7      onError={(error, errorInfo) => {
8        // Error is automatically logged with component stack
9      }}
10    >
11      <MyComponent />
12    </VestigErrorBoundary>
13  )
14}

Best Practices

1. Always Wrap Unknown Errors

typescript

1try {
2  await externalLibrary.doSomething()
3} catch (unknownError) {
4  // Wrap with context
5  const error = new Error('External operation failed', {
6    cause: unknownError
7  })
8  log.error('Operation failed', { error })
9}

2. Use Appropriate Log Levels

typescript

1// Expected errors (business logic) → warn
2log.warn('User not found', { error, userId })
3 
4// Unexpected errors (bugs, system failures) → error
5log.error('Database connection failed', { error })
6 
7// Fatal errors (app can't continue) → error with context
8log.error('Failed to initialize', { error, fatal: true })

3. Include Context

typescript

1try {
2  await processOrder(orderId)
3} catch (error) {
4  log.error('Order processing failed', {
5    error,
6    orderId,
7    userId: ctx.userId,
8    action: 'process_order',
9  })
10}

4. Handle Rejected Promises

typescript

1// Option 1: Try/catch with async/await
2async function handler() {
3  try {
4    await riskyOperation()
5  } catch (error) {
6    log.error('Operation failed', { error })
7  }
8}
9 
10// Option 2: Promise .catch()
11riskyOperation()
12  .catch(error => log.error('Operation failed', { error }))
13 
14// Option 3: Global unhandled rejection handler
15process.on('unhandledRejection', (reason) => {
16  log.error('Unhandled promise rejection', {
17    error: reason
18  })
19})

5. Don't Log Sensitive Data

typescript

1// ❌ Bad: May include passwords, tokens
2log.error('Auth failed', { error, credentials })
3 
4// ✅ Good: Log only safe metadata
5log.error('Auth failed', {
6  error,
7  username: credentials.username,
8  // Don't include password
9})

API Reference

Types

typescript

1interface SerializedError {
2  name: string
3  message: string
4  stack?: string
5  cause?: SerializedError
6  code?: string | number
7  statusCode?: number
8  status?: number
9  errno?: number
10  syscall?: string
11  path?: string
12  address?: string
13  port?: number
14  [key: string]: unknown
15}

Functions

Function	Description
`serializeError(error, depth?)`	Serialize error with cause chain
`isError(value)`	Check if value is error-like
`getErrorMessage(error)`	Extract message from any value

Integration with Transports

All Vestig transports receive serialized errors:

typescript

1import { createLogger, ConsoleTransport, HTTPTransport } from 'vestig'
2 
3const logger = createLogger({
4  transports: [
5    new ConsoleTransport(), // Pretty-prints errors with colors
6    new HTTPTransport({
7      endpoint: '/api/logs'  // Sends serialized error JSON
8    })
9  ]
10})
11 
12// Errors are automatically serialized for all transports
13logger.error('Critical failure', { error: new Error('Something broke') })