# std::uncaught_exception, std::uncaught_exceptions

> C++ Atlas: `cppatlas.com/w/cpp/error/uncaught_exception` | Source: https://en.cppreference.com/w/cpp/error/uncaught_exception | Domain: Diagnostics | Standards: C++11, C++17, C++20, C++26

Sometimes it's safe to throw an exception even while std::uncaught_exception() == true(until C++17) std::uncaught_exceptions() > 0(since C++17).

## Official Specification Summary (cppreference)

```cpp
// Defined in header <exception>
bool uncaught_exception() throw(); // (1) (until C++11)
bool uncaught_exception() noexcept; // (1) (since C++11) (deprecated in C++17) (removed in C++20)
int uncaught_exceptions() noexcept; // (2) (since C++17) (constexpr since C++26)
```

1) Detects if the current thread has a live exception object, that is, an exception has been thrown or rethrown and not yet entered a matching catch clause, `std::terminate` or `std::unexpected`. In other words, `std::uncaught_exception` detects if stack unwinding is currently in progress.

2) Detects how many exceptions in the current thread have been thrown or rethrown and not yet entered their matching catch clauses.

Sometimes it's safe to throw an exception even while `std::uncaught_exception() == true` (until C++17) `std::uncaught_exceptions() > 0` (since C++17). For example, if stack unwinding causes an object to be destructed, the destructor for that object could run code that throws an exception as long as the exception is caught by some catch block before escaping the destructor.

### Parameters

(none)

### Return value

1) `true` if stack unwinding is currently in progress in this thread, `false` otherwise.

2) The number of uncaught exception objects in the current thread.

### Notes

An example where int-returning `uncaught_exceptions` is used is the boost.log library: the expression `BOOST_LOG(logger) << foo();` first creates a guard object and records the number of uncaught exceptions in its constructor. The output is performed by the guard object's destructor unless `foo()` throws (in which case the number of uncaught exceptions in the destructor is greater than what the constructor observed).

`std::experimental::scope_fail` and `std::experimental::scope_success` in LFTS v3 rely on the functionality of `uncaught_exceptions`, because their destructors need to do different things that depend on whether is called during stack unwinding.

| Feature-test macro | Value | Std | Feature |
| --- | --- | --- | --- |
| `__cpp_lib_uncaught_exceptions` | `201411L` | (C++17) | `std::uncaught_exceptions` |
| `__cpp_lib_constexpr_exceptions` | `202411L` | (C++26) | `constexpr` for exception types |

### Example

```cpp
#include <exception>
#include <iostream>
#include <stdexcept>

struct Foo
{
    char id{'?'};
    int count = std::uncaught_exceptions();

    ~Foo()
    {
        count == std::uncaught_exceptions()
            ? std::cout << id << ".~Foo() called normally\n"
            : std::cout << id << ".~Foo() called during stack unwinding\n";
    }
};

int main()
{
    Foo f{'f'};

    try
    {
        Foo g{'g'};
        std::cout << "Exception thrown\n";
        throw std::runtime_error("test exception");
    }
    catch (const std::exception& e)
    {
        std::cout << "Exception caught: " << e.what() << '\n';
    }
}
```

Possible output:

```text
Exception thrown
g.~Foo() called during stack unwinding
Exception caught: test exception
f.~Foo() called normally
```

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 70 | C++98 | the exception specification of `uncaught_exception()` was missing | specified as `throw()` |

### See also

- [`terminate`](https://en.cppreference.com/w/cpp/error/terminate): function called when exception handling fails (function)
- [`exception_ptr`](https://en.cppreference.com/w/cpp/error/exception_ptr) (C++11): shared pointer type for handling exception objects (typedef)
- [`current_exception`](https://en.cppreference.com/w/cpp/error/current_exception) (C++11): captures the current exception in a `std::exception_ptr` (function)

### External links

|   |   |
| --- | --- |
| 1. | GOTW issue 47: Uncaught Exceptions |
| 2. | Rationale for `std::uncaught_exceptions` (N4125) |

---
Attribution: content from https://en.cppreference.com/w/cpp/error/uncaught_exception (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.