Modern Error Handling

Choose the right tool

• Use exceptions for exceptional failures that should cross multiple layers.
• Use std::optional<T> when absence is normal and there is no extra error detail.
• Use std::expected<T, E> when callers should handle a typed error locally.
• Use std::variant<Ts...> when a result can be one of several valid shapes.

std::optional

std::optional<int> find_id(std::string_view name);

if (auto id = find_id("ada")) {
    std::cout << *id << '\n';
}

Use it for "maybe there is a value". Do not overload it with detailed failure reasons.

std::optional<User> find_user(Id id);

If callers always need to know why lookup failed, optional is the wrong type.

std::expected

enum class ParseError { invalid_digit, overflow };

std::expected<int, ParseError> parse_port(std::string_view text);

std::expected keeps the success path explicit and makes error propagation testable.

auto port = parse_port(text);
if (!port) {
    return std::unexpected(port.error());
}

std::variant

using ConfigValue = std::variant<int, bool, std::string>;

Visit a variant when the set of alternatives is fixed and meaningful.

std::visit([](const auto& value) {
    handle(value);
}, config_value);

Practical guidance

• Keep error types small and domain-specific.
• Do not mix exceptions and expected randomly in the same layer.
• Mark must-check results with [[nodiscard]].

Layering rule of thumb

• low-level parsing or validation: often expected
• domain lookup where absence is normal: often optional
• application boundary or truly exceptional failure: often exceptions

Quick selection rules

• optional: missing value is normal.
• expected: caller should branch on success vs error.
• variant: multiple valid shapes.
• exceptions: failure should unwind across layers.

Pitfalls to avoid

• using exceptions and expected for the same kind of failure in one layer
• storing oversized or overly generic error payloads
• returning optional when callers immediately need a failure reason