Skip to main content

TypeScript Error Type Handling in Try-Catch Blocks

Handling errors in TypeScript is essential for building reliable applications. With TypeScript's type safety features, developers can catch errors during the development phase, reducing the risk of issues when the application runs. In this article, we'll explore how to handle errors in TypeScript, including creating specific error types, effectively catching and dealing with errors, and using type guards to refine them. Whether you're an experienced developer or new to TypeScript, this guide will equip you with the skills to improve your error handling.

Defining Specific Error Types​

Creating specific error types helps you catch and handle errors with precision in TypeScript. By defining custom error classes or interfaces, you can provide more context about what went wrong, making errors easier to debug.

interface NetworkError extends Error {
  statusCode: number;
}

class NetworkErrorClass extends Error {
  statusCode: number;

  constructor(message: string, statusCode: number) {
    super(message);
    this.statusCode = statusCode;
    // Set the prototype explicitly.
    Object.setPrototypeOf(this, NetworkErrorClass.prototype);
  }
}

Note that when extending the Error class in TypeScript, you should set the prototype explicitly as shown above. This ensures that instanceof checks work correctly after transpilation to JavaScript.

When working with a backend like Convex, you can create application-specific error types that align with your system's domains. For example, you might create authentication errors, validation errors, or resource-not-found errors. Convex's error handling system provides built-in support for distinguishing between different error types.

Catching and Handling Errors Effectively​

The try-catch block works like it does in JavaScript, but TypeScript adds type safety features like type guards to help specify error types.

try {
  // code that might throw an error
} catch (error) {
  if (error instanceof NetworkErrorClass) {
    console.log(`Network error with status code ${error.statusCode}`);
  } else {
    console.log('Unknown error');
  }
}

In this example, we're using the instanceof operator to check if the caught error is of type NetworkErrorClass. This allows us to access the statusCode property safely.

When working with modern TypeScript (4.4+), the error variable in catch blocks is typed as unknown by default. This is safer than the previous any type, as it forces you to verify the error's type before accessing its properties.

If you're using try catch with Convex functions, you can leverage Convex's structured approach to errors to distinguish between different types of failures and handle them accordingly in your client code.

Using TypeScript's unknown Type for Error Catching​

The unknown type in TypeScript offers a safer alternative to any for error catching. By declaring an error as unknown, developers ensure that they perform type checks before using it.

try {
  // code that might throw an error
} catch (error: unknown) {
  if (error instanceof Error) {
    console.log(error.message);
  } else {
    console.log('Unknown error');
  }
}

When using the unknown type, you must perform type assertion or use type guards before accessing properties. This prevents runtime errors from unchecked property access.

In TypeScript projects using Convex for the backend, you can leverage end-to-end type safety from your database schema to your React app. This approach helps ensure that errors from server functions are properly typed and handled in the client.

While typeof can help with basic type checking, instanceof is more reliable for checking custom error classes. You can also create custom type guards for more complex error validation.

Implementing Custom Error Classes​

Custom error classes add context and information to errors in TypeScript. By creating these classes, developers can define properties and methods that provide more insights into the error.

class ValidationError extends Error {
  field: string;

  constructor(message: string, field: string) {
    super(message);
    this.field = field;
    // Important: Set the prototype explicitly for proper instanceof checks
    Object.setPrototypeOf(this, ValidationError.prototype);
  }
}

When throwing these custom errors, you can be specific about what went wrong:

function validateEmail(email: string): void {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    throw new ValidationError('Invalid email format', 'email');
  }
}

Using class inheritance with Error gives you type safety while maintaining JavaScript's error handling patterns. The constructor in custom error classes should always call super(message) to properly initialize the base Error properties.

When working with complex database systems, custom error classes can help distinguish between different failure modes when accessing related documents.

If you're using TypeScript with React, custom errors can improve how your application communicates failures to users, turning generic errors into actionable messages.

Using TypeScript's try-catch Block with Type Safety​

TypeScript allows you to catch errors with type safety by declaring an error variable as a specific error type. This feature helps ensure you handle errors appropriately.

try {
  // code that might throw an error
} catch (error: NetworkErrorClass | ValidationError) {
  // Type guards to refine the error type
  if (error instanceof NetworkErrorClass) {
    console.log(`Network error with status code ${error.statusCode}`);
  } else if (error instanceof ValidationError) {
    console.log(`Validation error in field ${error.field}`);
  }
}

The try catch pattern in TypeScript is enhanced by type guards, which let the compiler know what properties are available on the error object. Using utility types with errors can also improve your error handling.

For backend development with Convex, you can benefit from schema validation to prevent many errors before they occur. This works well with TypeScript's typing system to create a more robust application.

Handling Errors with Union Types​

Handling errors with union types is common in TypeScript. By declaring an error variable as a union type, developers can use type guards to determine its type.

try {
  // code that might throw an error
} catch (error: NetworkErrorClass | ValidationError | Error) {
  if (error instanceof NetworkErrorClass) {
    console.log(`Network error with status code ${error.statusCode}`);
  } else if (error instanceof ValidationError) {
    console.log(`Validation error in field ${error.field}`);
  } else {
    console.log(error.message);
  }
}

The union types feature lets you specify multiple possible types for a variable. When working with errors, this means you can handle different error categories with type safety.

Convex's API generation system automatically creates TypeScript types for your backend functions, which makes error handling across the frontend-backend boundary more reliable.

Refining Error Types with Type Guards​

Type guards are a powerful way to refine error types in TypeScript. By using them, developers can ensure they handle specific error types correctly.

function isNetworkError(error: unknown): error is NetworkErrorClass {
  return error instanceof NetworkErrorClass;
}

try {
  // code that might throw an error
} catch (error: unknown) {
  if (isNetworkError(error)) {
    console.log(`Network error with status code ${error.statusCode}`);
  } else {
    console.log('Unknown error');
  }
}

Custom type guards like the one above create a cleaner way to check error types. Instead of repeating instanceof checks throughout your code, you can centralize the logic in reusable functions.

For complex validation scenarios, consider using generics<T> with your error types to create flexible error handling patterns.

Final Thoughts on TypeScript Error Handling​

TypeScript error handling combines type safety with JavaScript's error patterns to create more reliable applications. By defining specific error types, using type guards, and leveraging TypeScript's features, you'll catch errors earlier and handle them more effectively.

When building applications with Convex, you benefit from end-to-end type safety that extends to error handling. This approach helps prevent issues before they reach production.

The right error handling strategy turns cryptic failures into actionable information, improving both developer experience and application reliability.