Error handling

ApolloResponse

Use ApolloResponse.data to check if the server returned data:

1
if (response.data != null) {
2
  // Handle (potentially partial) data
3
} else {
4
  // Something wrong happened
5
  if (response.exception != null) {
6
    // Handle non-GraphQL errors
7
  } else {
8
    // Handle GraphQL errors in response.errors
9
  }
10
}

This is also true when calling toFlow() (e.g. with subscriptions) and watch() (with the normalized cache).

1
apolloClient.subscription(subscription).toFlow().collect { response ->
2
  if (response.data != null) {
3
    // Handle (potentially partial) data
4
  } else {
5
    if (response.exception != null) {
6
      // Handle non-GraphQL errors
7
    } else {
8
      // Handle GraphQL errors in response.errors
9
    }
10
  }
11
}

If you prefer throwing, you can use dataOrThrow() to get a non-null data:

1
val data = apolloClient.query(ExampleQuery()).execute().dataOrThrow()
2
// data is non-null

Different types of errors

Whenever you execute a GraphQL operation with Apollo Kotlin (or any other GraphQL client), two types of errors can occur:

• Fetch errors: a GraphQL response wasn't received because an error occurred while communicating with your GraphQL server. This might be an SSL error, a socket error because your app is offline, or a 500 or any other HTTP error. When a fetch error occurs, no data is returned and response.exception is non-null.
• GraphQL errors: a GraphQL response is received (HTTP 200), and it contains a non-empty errors field. This means the server wasn't able to completely process the query. The response might include partial data if the server was able to process some of the query.

Fetch errors

Fetch errors happen when it's impossible to fetch a GraphQL response. They can have a wide variety of causes (non-exhaustive list):

• The app is offline or doesn't have access to the network.
• A DNS error occurred, making it impossible to look up the host.
• An SSL error occurred (e.g., the server certificate isn't trusted).
• The connection was closed.
• The server responded with a non-successful HTTP code.
• The server didn't respond with valid JSON.
• The response JSON doesn't satisfy the schema and cannot be parsed.
• A request was specified as CacheOnly but the data wasn't cached.
• And more...

You can display an error based on the exception in response.exception

GraphQL errors

GraphQL errors happen when a GraphQL response is successfully fetched but contains GraphQL errors. In that case, the response may contain partial data.

For example, the following query uses an invalid id to look up a Person:

1
query FilmAndPersonQuery {
2
  film(id: "ZmlsbXM6MQ==") {
3
    title
4
  }
5
  person(id: "badId") {
6
    name
7
  }
8
}

The server will return the following response:

1
{
2
  "data": {
3
    "film": {
4
      "title": "A New Hope"
5
    },
6
    "person": null
7
  },
8
  "errors": [
9
    {
10
      "message": "Cannot find person with id 'badId'",
11
      "path": ["person"]
12
    }
13
  ]
14
}

person is null:

1
// there was an error fetching data
2
println(response.data?.person) // null
3
// read the error from response.errors
4
println(response.errors?.first()?.message) // "Cannot find person with id 'badId'"
5
// partial data is also returned
6
println(response.data?.film?.title) //  "A New Hope"
7
// exception is null
8
println(response.exception) // null

This allows to display as much data as possible without having to do a new network round trip.

Because GraphQL models both errors and semantic nulls as nullable fields, you must check errors to determine whether the field is an error or a true null.

For an example, it is possible for a person to not have a starship:

1
{
2
  "data": {
3
    "person": {
4
      "starship": null
5
    }
6
  }
7
}

In that case, starship is a true null and not an error.

Handling GraphQL errors at parsing time

Because making the difference between true nulls and error nulls is cumbersome, Apollo Kotlin offers a way to handle errors automatically at parsing time. Fields that are nullable only for error purposes can also be generated as non-null in Kotlin. Read "handling nullability" for more details.