A Practical Checklist for Modern C++ Error Handling and Exceptions

Why Error Handling Still Breaks Production Code

Every C++ developer has faced the moment when an unhandled exception or a silently ignored error code causes a cascade of failures in production. Despite decades of language evolution, error handling remains one of the most inconsistently applied aspects of C++ programming. Teams often mix exceptions, error codes, and optional types without a coherent strategy, leading to code that is hard to reason about and even harder to maintain. The core problem isn't the lack of tools—it's the lack of a systematic approach. This guide addresses that gap by providing a practical checklist you can apply to any C++ project, from embedded systems to high-performance servers.

The Real Cost of Inconsistent Error Handling

When error handling is ad hoc, two things happen: developers ignore return values because they are tired of checking them, or they wrap everything in try-catch blocks that obscure the normal flow. Both behaviors lead to bugs that manifest only under rare failure conditions. For example, one team I worked with had a network library that returned error codes for connection failures but threw exceptions for timeouts. Callers frequently forgot to check the return code, assuming all errors would throw. The result: intermittent crashes that took weeks to diagnose. A unified strategy eliminates such ambiguity.

What This Checklist Covers

This article is organized as a sequence of decisions you can walk through when designing or reviewing code. We start with the fundamental choice between exceptions and error codes, then move to modern C++ features like std::expected (C++23) and std::optional. We'll also cover exception safety guarantees, resource cleanup using RAII, and testing strategies for error paths. Each section ends with actionable items you can add to your team's coding standards or code review checklist.

The stakes are high: poor error handling leads to data corruption, security vulnerabilities, and customer-facing outages. By investing upfront in a clear strategy, you reduce debugging time and increase code reliability. Let's begin by examining the two dominant paradigms and when to use each.

Exceptions vs. Error Codes: Choosing the Right Tool

The first decision in any C++ error-handling strategy is whether to use exceptions or error codes. Both have their advocates, and both have legitimate use cases. The key is to understand the trade-offs in terms of performance, code clarity, and maintainability. Exceptions provide separation of error handling from normal code, but they impose a runtime cost and can make control flow harder to follow. Error codes are explicit and efficient, but they require discipline to check at every call site. Many modern C++ projects use a hybrid approach: exceptions for exceptional conditions and error codes for expected failures.

When Exceptions Shine

Exceptions are ideal for conditions that are truly exceptional and cannot be handled locally. For example, a memory allocation failure or a file system error deep in a library call. In these cases, propagating the error via exceptions avoids cluttering every intermediate function with error-checking code. The C++ standard library itself uses exceptions for such scenarios (e.g., std::bad_alloc). Exceptions also support the Resource Acquisition Is Initialization (RAII) pattern naturally: destructors are called during stack unwinding, ensuring resources are released even when an exception propagates. However, exceptions should not be used for control flow or for conditions that callers can reasonably anticipate and handle, such as a failed parsing attempt.

When Error Codes Are Better

Error codes (or return-value-based error handling) work best when failures are frequent and must be handled immediately. For instance, in networking code, a socket read might fail because data is not yet available—this is an expected condition that the caller should handle by retrying or moving on. Using exceptions for such cases would be overkill and could harm performance in tight loops. Error codes also offer deterministic behavior: the cost of checking a return value is just a comparison, with no hidden stack unwinding. The downside is that error codes can be silently ignored. To mitigate this, modern C++ provides [[nodiscard]] attributes and wrapper types like std::expected that force callers to acknowledge errors.

A Practical Decision Matrix

Ultimately, the choice should be documented in your team's style guide. Consistency matters more than the specific choice. For instance, if you decide that all I/O errors throw exceptions, ensure that every I/O function in your codebase follows that rule. Mixing paradigms without clear boundaries leads to confusion and bugs.

Designing Exception-Safe Code with RAII

Exception safety is not just about catching exceptions—it's about writing code that remains in a valid state when exceptions occur. The cornerstone of exception safety in C++ is RAII (Resource Acquisition Is Initialization). By tying resource lifetimes to object lifetimes, you guarantee that destructors run during stack unwinding, releasing memory, mutexes, file handles, and other resources automatically. This section outlines the three exception safety guarantees and how to achieve them in practice.

The Three Guarantees

Herb Sutter popularized the classification of exception safety into three levels: basic, strong, and nothrow. The basic guarantee ensures that no resources are leaked and all objects are in a valid (though possibly unspecified) state. The strong guarantee ensures that if an exception is thrown, the program state is rolled back to exactly what it was before the operation—a transactional behavior. The nothrow guarantee promises that the operation will never throw, which is required for destructors, swap functions, and move operations. Most code should aim for the basic guarantee at minimum, while critical operations (like database commits) should strive for the strong guarantee.

Practical RAII Patterns

Use standard RAII wrappers whenever possible: std::unique_ptr for dynamic memory, std::lock_guard for mutexes, std::ofstream for file handles. If you need to manage a custom resource, write a small RAII class that acquires the resource in the constructor and releases it in the destructor. For example, to manage a POSIX file descriptor: class FileDescriptor { int fd; public: FileDescriptor(const char* path) : fd(open(path, O_RDONLY)) { if (fd == -1) throw std::runtime_error("open failed"); } ~FileDescriptor() { close(fd); } }; The destructor is noexcept by default, so cleanup is guaranteed. Avoid raw new/delete and C-style resource management; they are prone to leaks when exceptions strike.

Avoiding Common RAII Mistakes

One frequent mistake is throwing exceptions from destructors. If a destructor throws while another exception is already propagating, the program terminates. Always mark destructors as noexcept (the default) and handle any errors internally. Another pitfall is holding multiple resources in a single function without using RAII for each. For instance, if you open two files and the second open throws, the first file leaks unless you wrap both in RAII objects. The rule of thumb: each resource should be managed by its own RAII object, and those objects should be declared in order of acquisition so that destruction happens in reverse order automatically.

By consistently applying RAII, you eliminate most resource leaks and make your code inherently exception-safe. The remaining challenge is to ensure that the logic itself is safe—for example, by using copy-and-swap for assignment operators to achieve the strong guarantee. Next, we'll look at how modern C++ types like std::expected and std::optional can reduce reliance on exceptions for expected failures.

Leveraging std::expected and std::optional for Clear Error Paths

C++17 introduced std::optional, and C++23 brought std::expected, giving developers powerful tools to handle expected failures without exceptions. These types make the error path explicit in the function signature, improving code readability and forcing callers to deal with errors. Unlike exceptions, they have zero runtime overhead when no error occurs (the valueless state still requires some overhead, but typically less than stack unwinding). This section explains how to use these types effectively and when they are preferable to exceptions.

std::optional: When There Might Be No Value

std::optional represents a value that may or may not be present. It is ideal for functions that can fail in a single, simple way—for example, a lookup that might not find a key. The caller can check has_value() or use value_or() to provide a default. However, std::optional does not carry information about why the failure occurred. If you need to distinguish between multiple error reasons, std::expected is a better fit. A common pattern is to return std::optional for operations where failure is common and the caller is expected to handle it immediately, such as parsing user input.

std::expected: Error Codes with Modern Syntax

std::expected holds either a value of type T or an error of type E. It behaves like a discriminated union, similar to Rust's Result type. You can use it to return rich error information without exceptions. For example: std::expected parse_int(const std::string& s);. The caller can then use has_value() to check success or access the error via error(). std::expected supports monadic operations like and_then, or_else, and transform, enabling error-handling chains without nested if statements. This is particularly useful in functional-style code.

When to Use Which

Use std::optional when the failure is binary (success or failure) and the caller doesn't need to know the cause. Use std::expected when you need to convey specific error information, such as an error code or a string message. Use exceptions for errors that are truly exceptional and cannot be handled locally, or when the call stack is deep and error propagation via return values would be cumbersome. A good rule of thumb: if the error is expected to occur in normal operation (e.g., file not found, network timeout), use std::expected or std::optional. If the error indicates a bug or system resource exhaustion, use exceptions.

Adopting these types consistently reduces the number of try-catch blocks in your code and makes error paths visible at a glance. The next step is to ensure that your error handling is testable—a topic we cover in the following section.

Testing Error Paths: Ensuring Your Error Handling Works

Even the best-designed error handling is useless if it's not tested. Yet many teams focus on testing the happy path and neglect failure scenarios. This is a recipe for disaster: the first time a real error occurs, the error-handling code itself may have bugs. Testing error paths requires deliberate effort, but modern testing frameworks and techniques make it manageable. This section provides a practical approach to testing exceptions, error codes, and RAII cleanup.

Testing Exceptions

Use your test framework's assertion macros to verify that exceptions are thrown when expected. For example, with Google Test: EXPECT_THROW(parse_int("abc"), std::invalid_argument);. Also test that exceptions are not thrown on valid input. For code that should be exception-safe, write tests that inject failures. For instance, mock a memory allocator to throw std::bad_alloc at a specific point, then verify that the function does not leak resources and leaves the program state consistent. This technique, called fault injection, is crucial for verifying strong exception safety guarantees.

Testing std::expected and std::optional

For functions returning std::expected, test both the value and error paths. Check that has_value() returns true for valid inputs and false for invalid ones. Verify the error value matches expectations. For std::optional, test that has_value() and value_or() behave correctly. Also test that the monadic operations chain correctly: for example, and_then should propagate errors without calling the continuation. Property-based testing can help generate a wide range of inputs to uncover edge cases.

Testing RAII Cleanup

To verify that resources are released, use a resource counter. For example, create a class that increments a global counter on construction and decrements on destruction. Then, exercise code paths that throw exceptions and assert that the counter returns to its initial value. This technique works for any resource type. Additionally, use leak detectors like Valgrind or AddressSanitizer during testing to catch missed deallocations. These tools are especially valuable for detecting memory leaks in error paths that might not be covered by unit tests.

Finally, include error paths in your integration tests. Simulate network failures, disk full conditions, and permission errors to ensure the entire system reacts gracefully. Many teams set up chaos engineering experiments that randomly inject failures to validate robustness. By making error path testing a first-class citizen in your development process, you build confidence that your application can withstand real-world failures.

Common Pitfalls and How to Avoid Them

Even experienced C++ developers fall into traps when handling errors. This section catalogs the most common mistakes observed in production code and provides concrete mitigations. By being aware of these pitfalls, you can avoid them during code reviews and design sessions.

Silently Swallowing Exceptions

One of the most dangerous patterns is an empty catch block: catch (...) {}. This hides errors and makes debugging nearly impossible. If you must catch all exceptions, at least log the error and rethrow or abort. Another variation is catching an exception and ignoring it because "it shouldn't happen." It will happen, and you'll waste hours debugging. Always handle exceptions meaningfully or let them propagate to a higher-level handler that can log and terminate gracefully.

Ignoring Return Values

Before [[nodiscard]], it was easy to call a function that returns an error code and forget to check it. Modern compilers warn about unused [[nodiscard]] return values, but the attribute must be applied consistently. Enforce its use on all functions that return error codes or std::expected. Additionally, consider using std::ignore intentionally when you truly want to discard a result (e.g., a logging function's return value), but use it sparingly.

Throwing in Destructors

As mentioned earlier, throwing from a destructor during stack unwinding causes std::terminate. Always mark destructors as noexcept (the default) and handle errors internally, perhaps by logging and ignoring. If a destructor must fail (e.g., closing a file fails), consider redesigning: expose a separate close() function that can throw and is called explicitly before destruction.

Inconsistent Error Types

Using a mix of std::error_code, int error codes, enum, and string messages makes error handling chaotic. Standardize on a single error type, such as std::error_code or a custom error class derived from std::exception. If you must interface with legacy code, write adapters that convert between error types. Consistency reduces cognitive load and simplifies error propagation.

Overusing Exceptions for Control Flow

Exceptions are not for regular control flow. Using them to exit a loop or handle a common case is slow and confusing. Reserve exceptions for truly exceptional conditions. For expected conditions, use std::optional or std::expected. If you find yourself catching exceptions in a tight loop, refactor to use return values.

By avoiding these pitfalls, you'll write C++ code that is more robust and easier to maintain. The next section answers frequently asked questions about error handling in modern C++.

Frequently Asked Questions About Modern C++ Error Handling

This section addresses common questions that developers ask when designing error-handling strategies. The answers reflect widely shared professional practices as of May 2026; verify critical details against current official guidance where applicable.

Should I use exceptions in embedded systems?

In many embedded environments, exceptions are disabled due to runtime overhead and lack of support. In such cases, use error codes or std::expected. However, if your embedded toolchain supports exceptions and you can afford the code size and performance impact, exceptions can simplify error handling in complex control flows. The key is to measure the overhead and set a policy. Some embedded projects use exceptions only during development for debug builds and disable them in release builds.

How do I handle errors in multi-threaded code?

Exceptions cannot cross thread boundaries. If a thread throws an unhandled exception, std::terminate is called. To communicate errors between threads, use a shared state, such as a std::future that can store an exception via std::promise::set_exception. Alternatively, use a thread-safe queue of error events. For thread pools, each task should catch exceptions and store the error in its result object. Avoid throwing exceptions from callback functions that run on a foreign thread; instead, return error codes.

What about noexcept functions that throw?

If a function marked noexcept throws, std::terminate is called. Use noexcept only for functions that you are certain cannot throw, such as destructors, move constructors, and swap functions. Do not mark a function noexcept if it calls code that might throw, unless you are prepared for termination. The compiler may optimize based on noexcept, so using it correctly can improve performance, but safety comes first.

How do I decide between std::error_code and custom exception classes?

std::error_code is lightweight and suitable for error codes that cross module boundaries. Custom exception classes are better when you need to carry contextual information, such as the file name and line number where the error occurred. A common pattern is to use a base exception class that stores an std::error_code and additional data, combining the benefits of both approaches.

These answers cover the most frequent concerns. For deeper guidance, refer to the C++ Core Guidelines and the ISO C++ committee papers on error handling.

Next Steps: Implementing Your Error Handling Checklist

You now have a comprehensive set of tools and principles to design robust error handling in C++. The final step is to apply them systematically. Here is a checklist you can use when starting a new module or reviewing existing code. Print it, pin it to your team's wiki, and refer to it during code reviews.

The Error Handling Checklist

• Choose a primary error-handling paradigm: exceptions, error codes, or a hybrid. Document the choice and the boundaries between exceptions and return-value-based errors.
• Apply RAII consistently: every resource should be managed by an RAII wrapper. Verify that destructors are noexcept and do not throw.
• Use std::optional and std::expected for expected failures. Prefer them over exceptions for local, recoverable errors.
• Mark functions with [[nodiscard]] when they return error codes or expected types. Enforce this with compiler warnings.
• Test error paths: write unit tests for exception throws, error code returns, and resource cleanup under failure.
• Standardize error types: pick one error representation (e.g., std::error_code) and use it throughout the codebase.
• Avoid empty catch blocks: always log or rethrow. Never swallow exceptions silently.
• Document exception safety guarantees for each function: basic, strong, or nothrow.

Start Small, Iterate

You don't have to refactor your entire codebase overnight. Pick one module or subsystem and apply the checklist. Over time, the patterns will become second nature. Share your experiences with your team and adjust the checklist based on lessons learned. Remember that error handling is an investment: the time you spend now will save countless hours of debugging later.

Finally, keep learning. The C++ standard evolves, and new tools like std::expected and std::error_code improve with each iteration. Follow the C++ Core Guidelines, read papers from ISO meetings, and participate in community discussions. By staying current, you'll ensure that your error handling remains effective as the language advances.