Error handling

You can use response.data to check if the server returned valid data:

1
val response = apolloClient.query(ExampleQuery()).execute()
2
// Using 'data' to be able to do a smart cast below (KT-8819)
3
val data = response.data
4

5
when {
6
  data != null -> {
7
    // data can be smart cast to non-null here
8
    println("The server returned data: $data")
9
  }
10
  else -> {
11
    // an error happened, check response.exception for more details or just display a generic error 
12
    when (response.exception) {
13
      is ApolloGraphQLException -> // do something with exception.errors
14
      is ApolloHttpException -> // do something with exception.statusCode
15
      is ApolloNetworkException -> TODO()
16
      is ApolloParseException -> TODO()
17
      else -> // generic error
18
    }
19
  }
20
}

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 data
4
  } else {
5
    // handle exceptions
6
  }
7
}

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 high-level types of errors can occur:

• Network 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 network error occurs, no data is returned.
• GraphQL errors: a GraphQL response is received, 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.

GraphQL errors

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 send the following response:

1
{
2
  "data": {
3
    "film": {
4
      "title": "A New Hope"
5
    },
6
    "person": null
7
  },
8
  "errors": [
9
    {
10
      "message": "No entry in local cache for https://swapi.dev/api/people/m�H/",
11
      "locations": [
12
        {
13
          "line": 35,
14
          "column": 3
15
        }
16
      ],
17
      "path": [
18
        "person"
19
      ]
20
    }
21
  ]
22
}

Note that while there are errors, the query successfully returned the title of the film: A New Hope. In general, any error while executing an operation bubbles up to the next nullable field. In this case, person is nullable. In the worst case, response.data can be null if everything else is non-nullable.

When GraphQL errors happen, ApolloResponse.exception will be an instance of ApolloGraphQLException and you can use exception.errors to read the actual GraphQL errors.

Network errors

Network errors are more varied and can have different 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.
• More...

Ignoring partial data

Because errors may happen on any field in your query, your UI code needs to handle any nullable field. In the example above, data.person will be null:

1
query FilmAndPersonQuery {
2
  # wrong id here, null will be returned
3
  person(id: "badId") {
4
    name
5
  }
6
}

Your UI code needs to check for null:

1
if (data.person != null) {
2
  // display person
3
}

If you prefer to catch these errors at parsing time, you can make data.person non-nullable using the @nonnull directive:

1
extend type Query @nonnull(fields: "person")

Alternatively, you can check for errors in an interceptor and force data to null whenever a GraphQL error happens:

1
object ignorePartialDataInterceptor: ApolloInterceptor {
2
  override fun <D : Operation.Data> intercept(request: ApolloRequest<D>, chain: ApolloInterceptorChain): Flow<ApolloResponse<D>> {
3
    return chain.proceed(request).map {
4
      if (it.exception is ApolloGraphQLException) {
5
        // nullify data altogether
6
        it.newBuilder().data(null).build()
7
      } else {
8
        it
9
      }
10
    }
11
  }
12
}

Note that the null check is still required on person because this field has a nullable type in the GraphQL schema.