Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free

Error handling

Whenever you execute a with (or any other ), two high-level types of errors can occur:

Network errors

Network errors throw an ApolloException. To handle them, wrap your query in a try/catch block:

try {
val response = apolloClient.query(query).execute()
} catch(exception: ApolloException) {
// handle exception here


Possible causes of a network error include (but are not limited to):

  • 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.

Examine the exception for more detailed information about the actual error.

GraphQL errors

Because GraphQL errors might still contain data, they do not throw. Instead, they return a Response with a Response.errors field indicating the errors that occurred.

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

query FilmAndPersonQuery {
film(id: "ZmlsbXM6MQ==") {
person(id: "badId") {

The server will send the following response:

"data": {
"film": {
"title": "A New Hope"
"person": null
"errors": [
"message": "No entry in local cache for�H/",
"locations": [
"line": 35,
"column": 3
"path": [

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, can be null if everything else is non-nullable.

Apollo Kotlin gives you access to both the data and the errors in the Response class:

val response = try {
} catch(exception: ApolloException) {
// Network error, not much to do
throw exception
// It's possible to display the film title
val title =
if (title != null) {
// The person triggered an error
val person =
if (person != null) {
// do something with response.errors

Ignoring partial data

If you don't want to handle partial responses, you can simplify your error handling logic. ApolloResponse.dataAssertNoErrors returns a non-nullable data and throws if there are any errors. This way, you can handle all errors in a single catch {} block:

val data = try {
} catch(exception: ApolloException) {
// All network or GraphQL errors are handled here
throw exception
// No need for safe calls on data
val title =

Note that the safe call is still required on film because this field has a nullable type in the . There are ways to override this in codegen. For more details, learn about the @nonnull directive.

GraphQL variables
Custom scalars
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy