# Error Handling

3.7.0-rc 3.6.0 (latest) 3.5.0 3.4.0 3.3.0 3.2.0 2.48.0-rc 2.47.1 2.46.0 2.45.0 2.44.0 2.43.0 2.42.0 2.41.0 2.40.0 2.39.0 2.38.0 2.37.0 2.36.0 2.35.0 2.34.0 2.33.0 2.32.0 2.31.0 2.30.0 2.29.0 2.28.0 2.27.0 2.26.0 2.25.1 2.24.0 2.23.0 2.22.1 2.21.0 2.20.0 2.19.0 2.18.0 2.17.0 2.16.0 2.15.1 2.14.0 2.13.0 2.12.0 2.11.0 This library never throws exceptions to signal error. In general, the library returns a [StatusOr](https://docs.cloud.google.com/cpp/docs/reference/common/latest/classgoogle_1_1cloud_1_1StatusOr.html) if an error is possible. Some functions return objects that are not wrapped in a `StatusOr<T>` but will themselves return a `StatusOr<T>` to signal an error. For example, wrappers for asynchronous operations return `future<StatusOr<T>>`.

Applications should check if the `StatusOr<T>` contains a value before using it, much like how you might check that a pointer is not null before dereferencing it. Indeed, a `StatusOr<T>` object can be used like a smart-pointer to `T`, with the main difference being that when it does not hold a `T` it will instead hold a `Status` object with extra information about the error.

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. Alternatively, callers may instead use the `.value()` member function which is defined to throw a [RuntimeStatusError](https://docs.cloud.google.com/cpp/docs/reference/common/latest/classgoogle_1_1cloud_1_1RuntimeStatusError.html) if there is no value.

> [!NOTE]
> **Note:** If you're compiling with exceptions disabled, calling `.value()` on a `StatusOr<T>` that does not contain a value will terminate the program instead of throwing.

###### Example

      namespace spanner = ::google::cloud::spanner;
      [](spanner::Client client) {
        auto rows = client.Read("Albums", spanner::KeySet::All(), {"AlbumTitle"});
        // The actual type of `row` is google::cloud::StatusOr<spanner::Row>, but
        // we expect it'll most often be declared with auto like this.
        for (auto const& row : rows) {
          // Use `row` like a smart pointer; check it before dereferencing
          if (!row) {
            // `row` doesn't contain a value, so `.status()` will contain error info
            std::cerr << row.status();
            break;
          }

          // The actual type of `song` is google::cloud::StatusOr<std::string>, but
          // again we expect it'll be commonly declared with auto as we show here.
          auto song = row->get<std::string>("AlbumTitle");

          // Instead of checking then dereferencing `song` as we did with `row`
          // above, here we demonstrate use of the `.value()` member, which will
          // return a reference to the contained `T` if it exists, otherwise it
          // will throw an exception (or terminate if compiled without exceptions).
          std::cout << "SongName: " << song.value() << "\n";
        }
      }

###### See Also

[`google::cloud::StatusOr`](https://docs.cloud.google.com/cpp/docs/reference/common/latest/classgoogle_1_1cloud_1_1StatusOr.html)

###### See Also

[`google::cloud::Status`](https://docs.cloud.google.com/cpp/docs/reference/common/latest/classgoogle_1_1cloud_1_1Status.html) the class used to describe errors.

###### See Also

[`google::cloud::future`](https://docs.cloud.google.com/cpp/docs/reference/common/latest/classgoogle_1_1cloud_1_1future.html) for more details on the type returned by asynchronous operations.