Stay organized with collections Save and categorize content based on your preferences.
An overview of error handling in the Google Cloud C++ client libraries.
OverviewIn general, the google-cloud-cpp libraries return a StatusOr if a function may fail and needs to signal an error. StatusOr<T> is an "outcome", it contains either the value returned on success, or a description of the error. Errors are represented by Status, thus the name. If you are familiar with std::expected from C++23, StatusOr<T> plays a similar role, but does not attempt to be compatible with it.
If you are planning to log a Status, consider using the iostream operator<<. A Status contains more than just the message, in particular, its error_info() member function may return additional information that is useful during troubleshooting.
Some functions return StreamRange<S>, where S is a StatusOr<T>. These ranges provide input iterators that paginate or stream results from a service, offering a more idiomatic API. The value type in these iterators is StatusOr<T> because the stream may fail after it has successfully returned some values. For example, if the request to obtain the next page of results fails, or if the underlying stream is interrupted by the service.
Some functions return a "future" (future). These objects represent a value that will be obtained asynchronously. By the very nature of asynchronous operations, the request may fail after the function is called. Therefore, we have chosen to return future<StatusOr<T>>. We think the alternatives are either incorrect (e.g. StatusOr<future<T>> can only handle errors detected before the function returns), or overly complex (StatusOr<future<StatusOr<T>>>).
Some functions return a value that already has a mechanism to signal failures. For example:
std::unique_ptr<AsyncStreamingReadWriteRpc<T,U>>.std::istream or std::ostream.In such cases, the library does not wrap the result in a StatusOr<T> because the returned type already has mechanisms to signal errors.
You can check that a StatusOr<T> contains a value by calling the .ok() method, or by using operator bool() (like with other smart pointers). If there is no value, you can access the contained Status object using the .status() member. If there is a value, you may access it by dereferencing with operator*() or operator->(). As with all smart pointers, callers must first check that the StatusOr<T> contains a value before dereferencing and accessing the contained value.
namespace gc = ::google::cloud;
[](std::string const& project_name) {
gc::StatusOr<gc::Project> project = gc::MakeProject(project_name);
if (!project) {
std::cerr << "Error parsing project <" << project_name
<< ">: " << project.status() << "\n";
return;
}
std::cout << "The project id is " << project->project_id() << "\n";
}
Some applications prefer to throw exceptions on errors. In this case, consider using StatusOr::value(). This function throws a RuntimeStatusError if there is no value, and returns the value otherwise.
.value() on a StatusOr<T> that does not contain a value will terminate the program instead of throwing.
namespace gc = ::google::cloud;
[](std::string const& project_name) {
try {
gc::Project project = gc::MakeProject(project_name).value();
std::cout << "The project id is " << project.project_id() << "\n";
} catch (gc::RuntimeStatusError const& ex) {
std::cerr << "Error parsing project <" << project_name
<< ">: " << ex.status() << "\n";
}
}
The code samples for google-cloud-cpp try to emphasize how to use specific APIs and often have minimal error handling. A typical code sample may simply throw the status on error, like so:
namespace svc = ::google::cloud::some_service;
[](svc::Client client, std::string const& key) {
auto response = client.SomeRpc(key);
if (!response) throw std::move(response).status();
// ... example continues here ...
}
This should not be interpreted as a best practice. If your application is designed to work with exceptions, then using StatusOr::value() is a better alternative. We just want to show that some error handling is required for these functions, but at the same time we don't want to obscure the example with a lot of error handling code.
google::cloud::Status the class used to describe errors.
google::cloud::future for more details on the type returned by asynchronous operations.
google::cloud::AsyncStreamingReadWriteRpc for more details on error handling for this class template.
https://en.cppreference.com/w/cpp/utility/expected for more information about std::expected
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-14 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-14 UTC."],[[["The `google-cloud-cpp` libraries utilize `StatusOr\u003cT\u003e` to represent outcomes, encapsulating either a successful value or an error description via a `Status` object."],["`StreamRange\u003cS\u003e` is used by some functions to provide input iterators that may produce successful values or errors, where `S` represents `StatusOr\u003cT\u003e`."],["Asynchronous functions return `future\u003cStatusOr\u003cT\u003e\u003e` to represent the potential for errors after the function call, ensuring error handling in asynchronous operations."],["The library often returns values that have internal error-handling mechanisms, such as `AsyncStreamingReadWriteRpc\u003cT,U\u003e` or classes derived from `std::istream` or `std::ostream`, and as such, are not wrapped by `StatusOr\u003cT\u003e`."],["`StatusOr::value()` can be used to retrieve a value or throw a `RuntimeStatusError` if an error is present, enabling exception-based error handling in applications, but will terminate the program if the compiler has exceptions disabled."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4