Errors and Diagnostics

Introduction

The error domain separates exception handling from diagnostic presentation. Exception carries a reason and an optional cause; Diagnostic describes one exception as structured information. Diagnostic documents preserve that information for plain-text or terminal rendering.

For examples and handling strategies, see Throwing and Handling Exceptions and Working with Diagnostic Data.

Exception Categories

Exception is the neutral base class for all Erbsland Core exceptions and derives from std::exception. Its two main branches define how callers should handle a problem:

• RuntimeError represents recoverable data and operational errors. Catch this type, or a more specific subclass, where the application can recover. Runtime exception names end in Error.

• LogicFailure represents programming mistakes, broken invariants, or exhausted system resources with no practical recovery. Its subclasses have names ending in Failure.

Fatal failures remain exceptions: throwing one does not unconditionally terminate the process. Application boundaries should preserve their diagnostics and propagate them instead of treating them as recoverable input errors. Production code must not catch failures to return fallbacks or wrap them in runtime errors. The OrThrow suffix identifies a throwing operation; it does not determine whether an exception is recoverable.

Recoverable Errors

The following domain-neutral types derive from RuntimeError.

Type	Meaning
OutOfRangeError	A value exceeds numeric bounds or a configured processing limit.
NotFoundError	A requested key or name is absent.
OverflowError	An operation results in an overflow.
ParseError	Text cannot be parsed as the requested value. The error can carry a code-point index, byte index, or code location.

Data-conversion factories use OutOfRangeError for invalid numeric data, ParseError for malformed encodings, and NotFoundError for unknown names. A factory can still report a fatal failure for an invalid algorithm selection or a missing required initialized object.

Fatal Failures

These types refine LogicFailure by identifying the violated precondition or capacity constraint.

Type	Meaning
ParameterFailure	A developer-supplied parameter violates a precondition, such as an infinite or unrepresentable repeat count.
OutOfRangeFailure	An internal bounds violation or an unsupported system or storage capacity.

Both types represent fatal failures. The distinction identifies whether an invalid caller parameter directly causes the failure.

Related Text Errors

The text domain provides more specific runtime errors:

• FormatError reports invalid format patterns, mismatched arguments, unsupported format options, and format output limit failures.

• ParseNumberError extends ParseError with the reader status that caused numeric parsing to fail.

Integer parsing reports invalid digits, invalid or disallowed base prefixes, invalid separators, missing digits, and strict trailing characters as parse errors.

Exception Details and Causes

Exception::reason() returns the stored human-readable reason. Exception::what() exposes it at the standard exception boundary, while Exception::toString() provides local display text for the exception.

An exception can preserve a separate failure layer as a std::exception_ptr. Use Exception::hasCause() and Exception::cause() to inspect this optional cause. Use DiagnosticHelper to include the cause chain in a diagnostic document.

Diagnostics

One Diagnostic or a Complete Document

Diagnostic describes one exception, with optional source name, source path, and CodeLocation metadata. Its document representation is a renderer-neutral TextDocument tree.

Choose the conversion according to the information you need:

• Exception::diagnostic() returns the diagnostic for one exception.

• Diagnostic::toTextDocument() converts one diagnostic to a document; Diagnostic::toString() renders it as plain text.

• DiagnosticHelper::toDiagnostic() adapts a caught std::exception to one diagnostic.

• DiagnosticHelper::toDocument() builds a document from the exception and its preserved causes.

• DiagnosticHelper::documentFromError() builds the document when you already have a std::exception_ptr.

Foreign standard exceptions become escaped fallback diagnostics. Unknown exceptions receive a neutral message, and excessively deep cause chains are limited.

Building Diagnostic Documents

ErrorDocumentBuilder supplies a consistent title, optional description, section headings, and source fields. Use its document root for domain-specific additions, then take the completed document with ErrorDocumentBuilder::takeDocument(). See Writing Custom Exceptions for custom exceptions and diagnostics.

The shared document structure keeps related information together:

• Metadata uses FieldList nodes below a diagnostic section heading. Each list aligns its own labels and values.

• Source excerpts use CodeSnippetMarker and TextNodeType::CodeSnippet nodes.

• Each cause uses a “Caused By” heading followed by a Blockquote, both with the diagnostic-cause style. The quote contains that cause’s diagnostic and, if present, the next heading and quote pair.

Developer-authored contexts and display text are trusted. Escape external values such as paths, command-line arguments, and native messages before rendering; use TextNode::addEscapedText() when inserting untrusted text into a document.

Rendering Diagnostic Documents

Use PlainTextRenderer or TextDocument::toString() for logs and redirected output. Plain rendering prefixes the root title with Error:, adds colons to section headings, and indents ordinary section content by two spaces, with another two spaces for each cause depth. Code snippets keep compact indentation and use │ as their gutter.

Use TerminalDocumentRenderer for styled terminal output. The default system-output style gives each cause depth a visible border and reserves the primary error color for the root diagnostic title. Cause headings and frames use subdued bright black. See Terminal Document Renderer for rendering and style details.

Interface

class Diagnostic : public std::enable_shared_from_this<Diagnostic>

Abstract diagnostic interface for one error.

Subclassed by erbsland::compression::impl::CompressionErrorDiagnostic, erbsland::conf::impl::ConfErrorDiagnostic, erbsland::core::impl::ApplicationErrorDiagnostic, erbsland::err::impl::ExceptionDiagnostic, erbsland::network::impl::NetworkErrorDiagnostic, erbsland::options::impl::OptionErrorDiagnostic, erbsland::path::impl::PathErrorDiagnostic, erbsland::re::impl::RegExErrorDiagnostic, erbsland::stream::impl::StreamErrorDiagnostic, erbsland::system::impl::PlatformErrorDiagnostic

Public Functions

virtual text::String sourceName() const noexcept

Get the source name, if this diagnostic points to one.

virtual text::String sourcePath() const noexcept

Get the source path, if this diagnostic points to one.

virtual unit::CodeLocation location() const noexcept

Get the source location, if this diagnostic points to one.

virtual text::String toString() const noexcept

Render this diagnostic as plain text.

virtual text::TextDocument toTextDocument() const

Render this diagnostic as a structured text document.

using erbsland::err::DiagnosticPtr = std::shared_ptr<Diagnostic>

Shared diagnostic pointer.

using erbsland::err::DiagnosticConstPtr = std::shared_ptr<const Diagnostic>

Shared diagnostic pointer for immutable diagnostics.

class DiagnosticHelper

A helper class to generate diagnostic documents.

Public Functions

explicit DiagnosticHelper(const std::exception &error)

Create a helper for one exception using the application display-text registry.

Parameters:

error – The exception to convert.

DiagnosticConstPtr toDiagnostic()

Create a diagnostic for one Erbsland Core exception.

Returns:

The diagnostic for the exception itself.

text::TextDocument toDocument()

Create a diagnostic document from an Erbsland Core exception, including causes.

Returns:

The diagnostic document.

Public Static Functions

static text::TextDocument documentFromError(const std::exception_ptr &errorPtr)

Create a diagnostic document from an exception pointer.

Parameters:

errorPtr – The exception pointer to convert.

Returns:

The diagnostic document.

class ErrorDocumentBuilder

Builds consistently styled error documents.

Public Functions

explicit ErrorDocumentBuilder(text::String title, text::String description = {})

Create a builder and add the initial title and optional description.

text::TextNodePtr addSection(text::String title)

Add a consistently styled diagnostic section heading.

void addSource(const text::String &sourceName, const text::String &sourcePath, unit::CodeLocation location)

Add available source name, path, and location fields.

text::TextDocument takeDocument()

Transfer the completed document out of this builder.

inline text::TextNodePtr root() const noexcept

Access the document root for domain-specific additions.

class Exception : public std::exception

The base class for all exceptions in this library.

Subclassed by erbsland::err::LogicFailure, erbsland::err::RuntimeError

Public Functions

Exception() noexcept = default

Create an empty exception.

explicit Exception(text::String reason)

Create an error with the given reason text.

Parameters:

reason – The reason for the exception.

explicit Exception(text::String reason, std::exception_ptr cause)

Create an error with the given reason text and diagnostic cause.

Parameters:

• reason – The reason for the exception.

• cause – The diagnostic cause.

explicit Exception(std::string_view reason)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

explicit Exception(std::string_view reason, std::exception_ptr cause)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

mem::UnsafeConstCharPtr what() const noexcept override

Return the exception reason as a null-terminated C string.

inline const text::String &reason() const noexcept

Get the reason text for the exception.

inline bool hasCause() const noexcept

Test if this exception has a diagnostic cause.

inline std::exception_ptr cause() const noexcept

Get the diagnostic cause.

virtual text::String toString() const noexcept

Convert the error with all its details into a string.

virtual DiagnosticConstPtr diagnostic() const

Convert the error with all its details into a structured diagnostic.

class LogicFailure : public erbsland::err::Exception

A fatal programming, invariant, or system-resource failure.

This class of exceptions is not meant to be caught and handled in user-code, instead they shall cause the program to abort.

Subclassed by erbsland::err::OutOfRangeFailure, erbsland::err::ParameterFailure, erbsland::random::RandomFailure

Public Functions

Exception() noexcept = default

Create an empty exception.

explicit Exception(text::String reason)

Create an error with the given reason text.

Parameters:

reason – The reason for the exception.

explicit Exception(text::String reason, std::exception_ptr cause)

Create an error with the given reason text and diagnostic cause.

Parameters:

• reason – The reason for the exception.

• cause – The diagnostic cause.

explicit Exception(std::string_view reason)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

explicit Exception(std::string_view reason, std::exception_ptr cause)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class NotFoundError : public erbsland::err::RuntimeError

A requested key or name was not found.

Public Functions

inline explicit NotFoundError(text::String reason) noexcept

Create a lookup error with a reason.

Parameters:

reason – The reason for the lookup error.

inline explicit NotFoundError(const std::string_view reason) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class OutOfRangeError : public erbsland::err::RuntimeError

An out-of-range error exception.

Reports recoverable numeric bounds and configured processing-limit errors.

Public Functions

inline explicit OutOfRangeError(text::String reason) noexcept

Create an out-of-range error with a reason.

Parameters:

reason – The reason for the out-of-range error.

inline explicit OutOfRangeError(const std::string_view reason) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class OutOfRangeFailure : public erbsland::err::LogicFailure

A bounds or capacity violation of an API precondition.

Public Functions

inline explicit OutOfRangeFailure(text::String reason) noexcept

Create a failure with a reason.

Parameters:

reason – The reason for the failure.

inline explicit OutOfRangeFailure(const std::string_view reason) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class OverflowError : public erbsland::err::RuntimeError

An overflow error exception.

These exceptions are thrown when an operation results in an overflow.

Public Functions

inline explicit OverflowError(text::String reason) noexcept

Create an overflow error exception with a reason.

Parameters:

reason – The reason for the overflow error.

inline explicit OverflowError(const std::string_view reason) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

class ParameterFailure : public erbsland::err::LogicFailure

A caller violation of a parameter precondition.

These exceptions are thrown when you pass invalid parameters to a function. Usually not meant to be caught by the application.

Public Functions

explicit ParameterFailure(text::String reason, text::String parameterName) noexcept

Create a parameter failure with a reason.

Parameters:

• reason – The reason for the parameter failure.

• parameterName – The name of the parameter that caused the error.

explicit ParameterFailure(std::string_view reason, std::string_view parameterName) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual text::String toString() const noexcept override

Convert the error with all its details into a string.

class ParseError : public erbsland::err::RuntimeError

A parse error exception.

These exceptions are thrown when text cannot be parsed as the requested value.

Subclassed by erbsland::text::ParseNumberError

Public Types

using Position = std::variant<std::monostate, unit::CpIndex, unit::ByteIndex, unit::CodeLocation>

A position in a parsed document.

Public Functions

explicit ParseError(text::String reason, const Position &position = {}) noexcept

Create a parse error with a reason.

Parameters:

• reason – The reason for the parse error.

• position – The optional code-point position of the parse error.

explicit ParseError(std::string_view reason, const Position &position = {}) noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual text::String toString() const noexcept override

Convert the error with all its details into a string.

virtual DiagnosticConstPtr diagnostic() const override

Convert the error with all its details into a structured diagnostic.

bool hasPosition() const noexcept

Test if this error has an associated position.

const Position &position() const noexcept

Get the position of the parse error.

inline unit::CpIndex codePointIndex() const noexcept

Get a code-point position or no-index if there is no code-point index.

inline unit::ByteIndex byteIndex() const noexcept

Get a byte index or no-index if there is no byte index.

inline unit::CodeLocation codeLocation() const noexcept

Get a code location or no-location if there is no code location.

class RuntimeError : public erbsland::err::Exception

A runtime exception.

Runtime exceptions are meant to be caught and handled in user-code.

Subclassed by erbsland::compression::CompressionError, erbsland::compression::zip::ZipError, erbsland::conf::ConfError, erbsland::core::ApplicationError, erbsland::cryptology::CryptologyError, erbsland::cryptology::SecureStorageError, erbsland::cryptology::TlsRecordError, erbsland::cterm::TerminalError, erbsland::err::NotFoundError, erbsland::err::OutOfRangeError, erbsland::err::OverflowError, erbsland::err::ParseError, erbsland::event::EventQueueFullError, erbsland::network::NetworkError, erbsland::network::impl::Http1ProtocolError, erbsland::network::impl::TlsProtocolError, erbsland::options::OptionError, erbsland::path::PathError, erbsland::re::RegExError, erbsland::resource::ResourceError, erbsland::stream::StreamError, erbsland::system::PlatformError, erbsland::text::EncodingError, erbsland::text::FormatError, erbsland::text::placeholder::ReplacerError, erbsland::text::render::RenderError, erbsland::text::render::impl::ProgramError, erbsland::util::WorkerCancelledError, erbsland::util::WorkerPoolClosedError, erbsland::util::WorkerPoolFullError, erbsland::util::impl::WorkerAdmissionError

Public Functions

Exception() noexcept = default

Create an empty exception.

explicit Exception(text::String reason)

Create an error with the given reason text.

Parameters:

reason – The reason for the exception.

explicit Exception(text::String reason, std::exception_ptr cause)

Create an error with the given reason text and diagnostic cause.

Parameters:

• reason – The reason for the exception.

• cause – The diagnostic cause.

explicit Exception(std::string_view reason)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

explicit Exception(std::string_view reason, std::exception_ptr cause)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.