How to throw an error in JavaScript

When an error occurs in your application, it’s crucial to provide meaningful feedback. Simply logging an error without context is like throwing a black box into the ocean and hoping someone finds it. You need to communicate the issue clearly, both to yourself during debugging and to your users when necessary.

Imagine your application is a restaurant. If a dish goes wrong, the chef needs to know what went awry. Was it the ingredients? The cooking time? Without this information, you can’t improve. Similarly, in programming, if you encounter an error, you should be able to trace it back to its source.

function handleError(error) {
  console.error("An error occurred: ", error.message);
  // Additional logging or user notification can go here
}

Using a custom error handler can help you manage this process effectively. Instead of letting the application crash silently, you can take proactive steps to log the error context and, if appropriate, inform the user. This way, you’re not just panicking; you’re taking control.

For example, consider using a structured approach to error handling. You might want to include information like the error code, the function in which it occurred, and even the stack trace. This data can be invaluable for debugging.

function logError(error, context) {
  const errorDetails = {
    message: error.message,
    stack: error.stack,
    context: context,
  };
  // Log to a monitoring service
  sendToMonitoringService(errorDetails);
}

By utilizing such a structured logging mechanism, you can identify patterns in errors and address them systematically. When you say something about errors, it’s not just about reporting; it’s about understanding the implications of those errors.

Moreover, if you’re working in a team, consistent error handling practices allow your colleagues to understand the issues without diving deep into the code. This shared understanding can speed up the debugging process significantly.

Remember that time you were debugging a particularly elusive bug, and you found a log message that pointed you in the right direction? That’s the power of good error reporting. It can save you hours or even days of frustration. So, when things go wrong, don’t just say something; say the right thing.

The generic Error object is for amateurs

Now, let’s talk about the generic Error object. Using it is like putting a band-aid on a broken leg. Sure, it covers the wound, but it doesn’t fix the problem. The generic Error object provides minimal information, and relying on it can lead you down a path of ignorance. You need to create specific error types that convey more than just a vague message.

For instance, instead of throwing a standard Error, you could define custom error classes that give context to the issue. This not only improves readability but also helps in handling different types of errors more gracefully. Here’s how you can implement a custom error class:

class DatabaseError extends Error {
  constructor(message, query) {
    super(message);
    this.name = "DatabaseError";
    this.query = query;
  }
}

With a custom error like DatabaseError, you can provide the query that caused the issue, making it easier to debug database-related problems. When you throw this error, you can include specific details that will aid in understanding what went wrong:

function queryDatabase(query) {
  try {
    // Simulate a database operation
    throw new DatabaseError("Failed to execute query", query);
  } catch (error) {
    logError(error, { operation: "Database Query", query });
  }
}

This approach not only gives you a clearer picture but also allows you to catch and handle different errors differently. For instance, you might want to retry a network request on a NetworkError but not on a DatabaseError. This granularity in error handling can significantly enhance the robustness of your application.

Another advantage of creating custom error objects is that they can carry additional properties. You can add an error code, a timestamp, or any other relevant information that can help in diagnosing the problem. This is especially useful in larger applications where pinpointing the source of an error might not be straightforward.

class ValidationError extends Error {
  constructor(message, fields) {
    super(message);
    this.name = "ValidationError";
    this.fields = fields;
  }
}

In this case, the ValidationError can carry a list of fields that failed validation. This means that when an error occurs, you can provide feedback not just on what went wrong but also on which specific inputs were problematic:

function validateUserInput(input) {
  const errors = [];
  if (!input.email) {
    errors.push("Email is required.");
  }
  if (!input.password || input.password.length  0) {
    throw new ValidationError("User input validation failed", errors);
  }
}

By throwing a ValidationError containing the problematic fields, you empower the calling code to provide precise feedback to users, enhancing their experience. This level of detail is what separates a mediocre application from a great one.

When you start defining your own error types, you elevate your error handling from basic to exceptional. You’re not just throwing errors; you’re throwing meaningful exceptions that carry weight and context. This allows you to build a more resilient application that can handle the unexpected with grace. As you integrate this practice into your workflow, you’ll find that the clarity it brings to error management is invaluable.

However, as you dive deeper into custom errors, remember to maintain a balance. Too many custom error types can lead to confusion and clutter. Aim for a hierarchy that makes sense within your application’s context. The fine line between a bug and an exceptional condition becomes clearer when you have the right tools to distinguish between them-

Now you have to clean up the mess

So you’ve thrown a nice, specific, custom error. Great. Your logging service is happy. But your application might be in a completely broken state. When a function throws an exception, it’s like pulling the emergency brake on a train. Everything stops, right where it is. If you were in the middle of a multi-step process, you might have left things half-done. A file might be open, a database transaction might be uncommitted, a UI element might be stuck in a “loading” state forever. This is the mess. And if you don’t clean it up, you’re just creating more bugs.

This is precisely what the finally block was invented for. It’s the janitorial closet of exception handling. Code inside a finally block is guaranteed to run, whether the try block completed successfully, or a catch block was executed, or even if the exception was not caught and is still propagating up the stack. It’s your one chance to restore order to the universe.

function processData(filePath) {
  let file;
  try {
    file = open(filePath);
    // ... do something with the file that might throw an error
  } catch (e) {
    logError(e);
    // You might re-throw the error here
    throw e;
  } finally {
    if (file) {
      file.close();
      console.log("File closed. Resources released.");
    }
  }
}

Forgetting to close the file is a classic resource leak. On a server application, that’s a death sentence. A few dozen unclosed file handles or database connections, and your application will keel over. The finally block is non-negotiable for resource management. It’s not just for files and network sockets, either. Think about any kind of state mutation. If you set a global isBusy flag to true at the beginning of an operation, you had better set it back to false when you’re done, even if “done” means “crashed and burned.”

let isProcessing = false;

async function doComplexThing() {
  if (isProcessing) {
    return;
  }
  
  isProcessing = true;
  showSpinner();

  try {
    await stepOne();
    await stepTwoWhichMightFail();
    await stepThree();
  } catch (error) {
    console.error("Complex thing failed", error);
    showErrorMessage("Something went wrong!");
  } finally {
    isProcessing = false;
    hideSpinner();
  }
}

In this UI example, if stepTwoWhichMightFail throws an error, without the finally block, the spinner would spin forever, and the isProcessing flag would be stuck on true, preventing the user from ever trying the operation again. The application is now in a zombie state. The cleanup in the finally block is what makes the application resilient.

Sometimes, cleanup is more complicated than just flipping a boolean or closing a handle. You might need to perform a rollback. If an operation involves writing to a database and then making a call to an external API, what happens if the API call fails? You’ve already written the data. Do you leave it there? This is where you have to think transactionally. If the whole operation can’t succeed, you need to undo the parts that did.

async function createUserAndBill(userInfo) {
  let userId = null;
  try {
    const user = await db.createUser(userInfo);
    userId = user.id;
    
    // This part might fail
    await paymentGateway.charge(userInfo.creditCard, 100);

    return user;
  } catch (error) {
    // The payment failed. We must clean up the user we created.
    if (userId) {
      await db.deleteUser(userId);
    }
    // Now throw a more specific error
    throw new BillingError("Payment failed, user creation rolled back.");
  }
}

This is the hard part of writing robust software. It’s not just about catching errors; it’s about ensuring that your application’s state remains consistent and predictable, no matter what goes wrong. Failing to clean up after an error is a bug. It’s a bug that might only show up under strange network conditions or when the disk is full, but it’s a bug nonetheless. This brings us to a very important distinction:

The fine line between a bug and an exceptional condition

What’s the difference between a bug and an exceptional condition? It’s a simple question, but the answer is the foundation of robust error handling. A bug is your fault. It’s a mistake in your code, a logical flaw. An exceptional condition is when the universe decides to throw a wrench in your perfectly good logic. The network cable gets unplugged. The hard disk fills up. The user types “bagel” into a field that expects a number. You can’t prevent these things, but you are expected to handle them gracefully.

Treating a bug like an exceptional condition is a cardinal sin of programming. It’s when you know a value should never, ever be null, but you wrap the code that uses it in a try...catch block just in case. This is lazy. It’s like knowing one of the legs on your chair is wobbly and instead of fixing it, you just get really good at catching yourself before you fall over. Eventually, you’re going to fail, and you’ll have a much bigger mess on your hands.

Here’s a classic bug:

function getFirstInitial(names) {
  // Bug: What if the 'names' array is empty?
  const firstPerson = names[0];
  return firstPerson[0];
}

If you pass an empty array to this function, it will throw a TypeError because you can’t get property 0 of undefined. The correct response is not to wrap this in a try...catch. The correct response is to fix the bug. The programmer made a faulty assumption. The code should have checked its inputs.

function getFirstInitial(names) {
  // Fixed: Handle the case of an empty or invalid input.
  if (!names || names.length === 0 || typeof names[0] !== 'string' || names[0].length === 0) {
    return '?'; // Or throw an IllegalArgumentException, your choice.
  }
  return names[0][0];
}

Now, contrast that with a true exceptional condition. You need to read a configuration file from disk. You have no control over whether that file actually exists, whether you have permission to read it, or whether some other joker has filled it with gibberish instead of valid JSON.

function loadConfiguration(filePath) {
  try {
    const fileContent = fs.readFileSync(filePath, 'utf8');
    return JSON.parse(fileContent);
  } catch (error) {
    if (error.code === 'ENOENT') {
      // Exceptional Condition: The file doesn't exist.
      // This is a predictable failure mode. We can handle it.
      console.warn(Configuration file not found at ${filePath}. Using defaults.);
      return getDefaultConfig();
    } else if (error instanceof SyntaxError) {
      // Exceptional Condition: The file is corrupt.
      throw new ConfigurationError(Failed to parse configuration file: ${error.message});
    } else {
      // It's something else, maybe a bug in our code or an
      // unexpected system issue. Re-throw it.
      throw error;
    }
  }
}

See the difference? In the first case, the error resulted from a flaw in the programmer’s logic. In the second, the error resulted from the state of the outside world, which the programmer correctly anticipated and handled. Using exceptions to handle bugs is a form of self-deception. It hides the underlying problem and allows your program to limp along in a potentially corrupted state. The bug is still there, lurking, waiting to cause even more damage later on.

This is where assertions come in. An assertion is a statement that a condition must be true at a certain point in the code. If it’s not, it means there is a bug. The program should crash, loudly. During development, this is exactly what you want. It points you directly to your faulty assumption.

function calculateDiscount(price, user) {
  // We have a bug if we ever call this with a null user.
  console.assert(user !== null, "User object must not be null.");
  
  if (user.isPremiumMember) {
    return price * 0.8;
  }
  return price;
}

If the assertion fails, you don’t add a catch block. You go find the code that called calculateDiscount with a null user and you fix it. The line is this: use exceptions for failures you expect and can handle, like a failed network request. Use assertions and defensive checks for programmer errors-things that should be impossible if the code is correct.