Diagnostics library
Exceptions, error_code-based reporting, system_error support, termination handlers, and diagnostic-adjacent utilities.
The diagnostics area covers two different error-reporting models in the standard library: exception-based failure and error_code-based status reporting. It also includes termination behavior, assertion diagnostics, and bridging points to C and OS-originated errors. This hub is the curated starting point when the question is about how C++ signals, categorizes, or propagates failures.
# Start Here
Exception model
Start here when the failure is represented by throwing and catching objects derived from std::exception.
Error codes and categories
Use this route when code reports failures without throwing, especially for OS/library integration and recoverable API results.
System and OS-facing failures
Use the system_error family when exceptions carry associated `error_code` values or when failures map onto system categories and portable `errc` conditions.
Termination and assertions
Start here when the program cannot continue, when assertion behavior matters, or when uncaught/forbidden failures trigger termination.
# Quick Map
| If you need to... | Start with | Why |
|---|---|---|
| Throw and catch standard exceptions | exception, logic_error, runtime_error | This is the core exception hierarchy for typed failure reporting through stack unwinding. |
| Represent an error without throwing | error_code, error_condition | The `error_code` model is the non-throwing diagnostics route, especially useful at API boundaries and OS-facing layers. |
| Map platform-specific errors onto portable conditions | error_category, errc, generic_category, system_category | Categories and conditions define the translation between raw platform values and portable semantic classes of failure. |
| Work with an exception object outside immediate catch scope | exception_ptr, current_exception, rethrow_exception | This is the route for capture, delayed transport, and rethrow of exception state. |
| Nest one exception inside another for higher-level context | nested_exception, throw_with_nested, rethrow_if_nested | Nested exceptions let higher layers add context without losing the original failure chain. |
| Handle logic vs runtime standard exception families | logic_error, runtime_error | The library splits precondition/usage failures from runtime/environment failures into different base families. |
| Control what happens when recovery is impossible | terminate, set_terminate, assert | This route covers program-ending diagnostics rather than recoverable failure handling. |
| Bridge to C/errno-style diagnostics | errno, C diagnostics | Use this route when the failure source originates in C APIs or errno-based operating-system conventions. |
# Exception Families
Logic errors
Use the logic-error family for invalid program state or API misuse that should often be prevented by caller correctness.
invalid_argument · domain_error · out_of_range · length_error
Runtime errors
Use the runtime-error family for failures that depend on environment, external resources, or execution-time conditions.
Exception transport
Capture and rethrow exceptions across threads, callbacks, or delayed-handling boundaries.
Nested context
Add contextual failure information while preserving the original exception underneath.
# Error Code Families
| Family | Use it for | Primary destinations |
|---|---|---|
| Concrete code values | Carrying an implementation- or API-specific error result. | error_code |
| Portable semantic conditions | Comparing failures by meaning instead of raw platform value. | error_condition, errc |
| Category mapping | Defining the namespace and translation behavior for error values. | error_category, system_category, generic_category |
| Exception bridge | Throwing an exception that preserves an associated error code. | system_error |
# Practical Routes
I need a standard exception type
Start from the standard exception families when the design already uses throwing exceptions and you need the best matching library type.
I need a non-throwing failure result
Use the error-code route first when APIs should report failures explicitly instead of unwinding through exceptions.
I need failure diagnostics at the process boundary
Use termination and assertion routes when the program is not expected to recover and you need diagnostics or policy hooks around that boundary.
# Boundary Lines
| This hub covers | Use a different hub for |
|---|---|
| Exception families, error-code reporting, system categories, terminate/assert diagnostics, and exception transport/nesting utilities. | static_assert and core language diagnostics when the issue is compile-time, not runtime; C diagnostics when the model is C-first and errno/assert-centric. |
| Runtime diagnostics in the standard library. | Thread support or other domain hubs when you already know the failing subsystem and only need its API surface, not the diagnostics model itself. |