Error Handling

H5CPP reports errors as exceptions, not return codes. Every CAPI call the library makes is wrapped by one of the H5CPP_CHECK_* macros in h5cpp/H5config.hpp; on failure the macro throws a typed exception derived from h5::error::any (which derives from std::runtime_error). The exception type identifies what was happening (open / close / read / write / create / append / misc) and on what kind of object (file / dataset / packet_table / attribute / group / property_list).

Exception hierarchy

Two roots, both in the h5::error namespace:

• h5::error::any — base type for every thrown exception. Inherits std::runtime_error, so a single catch (const std::exception&) will catch anything h5cpp throws.
• h5::error::rollback — separate hierarchy, does not inherit runtime_error. Reserved for transactional code paths that need to distinguish "stop the operation and undo" from "fatal error". Most application code can ignore the rollback hierarchy.

Under h5::error::any the tree fans out by HDF5 object kind. Each leaf type signals which operation failed:

Namespace	Leaf types	Thrown by
h5::error::io::file	open, close, read, write, create, misc	h5::open / h5::create on a file path
h5::error::io::dataset	open, close, read, write, append, create, misc	h5::open(fd, name), h5::read, h5::write, h5::create<T>
h5::error::io::packet_table	open, close, read, write, append, create, misc	packet-table append APIs (h5::pt_t)
h5::error::io::attribute	open, close, read, write, create, misc, delete_	h5::aread, h5::awrite, h5::acreate
h5::error::io::group	open, close, create, misc	h5::gopen, h5::gcreate
h5::error::property_list	argument, misc	property-list constructors / setters (h5::fapl_t, h5::dcpl_t, …)

Each kind also exposes an any type (e.g. h5::error::io::file::any) that catches every leaf in that category. This is the level most application code will catch on:

try {
    h5::ds_t ds = h5::open(fd, "/may/not/exist");
} catch (const h5::error::io::dataset::open& e) {
    // exact: dataset open failed
} catch (const h5::error::io::dataset::any& e) {
    // anything dataset-related — typed for the operation
} catch (const h5::error::any& e) {
    // fallback: anything h5cpp throws
} catch (const std::exception& e) {
    // ultimate fallback: anything at all
}

Error message format

Every exception carries a std::string what() message produced by the H5CPP_ERROR_MSG macro in h5cpp/H5config.hpp:

<source-file> line# <N> : <human-readable description>

The description comes from one of the canonical strings in h5::error::msg:: (create_file, open_dataset, select_hyperslab, …) or a custom string supplied at the throw site. Each message ends in a trailing ellipsis ("…") to make the messages identifiable at a glance in mixed-source logs.

Muting the native HDF5 error stack

HDF5's C API also writes its own diagnostic stack to stderr when a call fails. By default that stack is enabled, so a single thrown h5cpp exception emits both the C++ exception body and a multi-line HDF5 trace. For code that intentionally probes — checking whether a dataset exists by trying to open it, for example — the trace is noise. h5::mute() suppresses the C API stack; h5::unmute() restores the previous handler. Both functions are thread-safe.

The canonical "probe by try" pattern, used across the examples:

h5::mute();
bool exists;
try {
    auto ds = h5::open(fd, "/possibly/missing");
    exists = true;
} catch (const h5::error::io::dataset::open&) {
    exists = false;
}
h5::unmute();

Three production-example uses of this idiom in the tree: examples/attributes/attributes.cpp:224, examples/groups/groups.cpp:207, and the h5::exists helper itself.

The CHECK_* macros (internals)

Code inside h5cpp's headers does not write throw directly; it goes through one of six macros that map a return-code shape to the correct exception type:

Macro	Fires when	Typical use
H5CPP_CHECK_NZ(call, T, msg)	call returns < 0	most HDF5 functions (negative return = failure)
H5CPP_CHECK_EQ(call, T, msg)	call returns 0	functions whose 0 is the failure signal
H5CPP_CHECK_SIZE(call, T, msg)	call returns 0	size-returning functions (sentinel = 0)
H5CPP_CHECK_NULL(call, T, msg)	call returns nullptr	pointer-returning helpers
H5CPP_CHECK_PROP(id, T, msg)	static_cast<hid_t>(id) < 0	property-list arguments
H5CPP_CHECK_ID(id, T, msg)	static_cast<hid_t>(id) is 0	handle invariants on entry

T is the exception type from the hierarchy above; msg is one of the predefined strings in h5::error::msg:: (or a custom literal). The macros are not part of the user-facing surface but the patterns show up in every header — useful background for reading the code.

The rollback hierarchy

h5::error::rollback and its per-namespace variants (h5::error::io::rollback, h5::error::io::dataset::rollback, …) are reserved for code paths that need to signal "abort the current operation and unwind committed work" separately from "an error occurred". The rollback types do not inherit std::runtime_error, so a catch (const std::exception&) will NOT catch them. Catch the rollback hierarchy explicitly when you need it; otherwise it bubbles past application-level handlers.

Most h5cpp consumers will never need to catch a rollback exception — they're internal to the threaded pipeline (H5Pthreads.hpp, H5executor.hpp) and the FAPL-scoped worker pool.

All exception types

Every leaf type below has its own auto-generated reference page (click through for the constructor, the inheritance graph, and the brief description). Use the leaf type for fine-grained catches, the per-category any for "anything in this category", or h5::error::any as the project-wide root.

Category	Catch-all	Operation leaves	Rollback
I/O root	h5::error::io::any	(see categories below)	h5::error::io::rollback
File	h5::error::io::file::any	h5::error::io::file::open, h5::error::io::file::close, h5::error::io::file::read, h5::error::io::file::write, h5::error::io::file::create, h5::error::io::file::misc	h5::error::io::file::rollback
Dataset	h5::error::io::dataset::any	h5::error::io::dataset::open, h5::error::io::dataset::close, h5::error::io::dataset::read, h5::error::io::dataset::write, h5::error::io::dataset::append, h5::error::io::dataset::create, h5::error::io::dataset::misc	h5::error::io::dataset::rollback
Packet table	h5::error::io::packet_table::any	h5::error::io::packet_table::open, h5::error::io::packet_table::close, h5::error::io::packet_table::read, h5::error::io::packet_table::write, h5::error::io::packet_table::append, h5::error::io::packet_table::create, h5::error::io::packet_table::misc	h5::error::io::packet_table::rollback
Attribute	h5::error::io::attribute::any	h5::error::io::attribute::open, h5::error::io::attribute::close, h5::error::io::attribute::read, h5::error::io::attribute::write, h5::error::io::attribute::create, h5::error::io::attribute::delete_, h5::error::io::attribute::misc	h5::error::io::attribute::rollback
Group	h5::error::io::group::any	h5::error::io::group::open, h5::error::io::group::close, h5::error::io::group::create, h5::error::io::group::misc	(none)
Property list	h5::error::property_list::any	h5::error::property_list::argument, h5::error::property_list::misc	h5::error::property_list::rollback
Root	h5::error::any	(see categories above)	h5::error::rollback

See also

h5::mute h5::unmute h5::error::any h5::error::io::file::any h5::error::io::dataset::any Handles, Descriptors & Property Lists Conversion Policy RAII Handles