Handling nullability and errors

Nullability in GraphQL

GraphQL does not have a Result type. If a field errors, it is set to null in the JSON response and an error is added to the errors array.

With the following schema and query:

1
type User {
2
  id: ID!
3
  # name is nullable, but in practice this happens only in error cases
4
  name: String
5
  avatarUrl: String
6
}
7

8
query GetUser {
9
  user {
10
    id
11
    name
12
    avatarUrl
13
  }
14
}

The server returns the following response in case of error:

1
{
2
  "data": {
3
    "user": {
4
      "id": "1001",
5
      "name": null,
6
      "avatarUrl": "https://example.com/pic.png"
7
    }
8
  },
9
  "errors": [
10
    {
11
      "message": "Cannot resolve user.name",
12
      "path": ["user", "name"]
13
    }
14
  ]
15
}

GraphQL best practices recommend using nullable types by default. From graphql.org:

This default makes sense in distributed environments where microservices might fail and some data fail to resolve. This behaviour is robust by default: if part of your query fails, you still get the rest of the data.

This default has one major drawback for frontend developers though. It requires to carefully check every field in your UI code.

Sometimes it's not clear how to handle the different cases:

1
@Composable
2
fun User(user: GetUserQuery.User) {
3
  if (user.name != null) {
4
    Text(text = user.name)
5
  } else {
6
    // What to do here? 
7
    // Is it an error? 
8
    // Is it a true null?
9
    // Should I display a placeholder? an error? hide the view?
10
  }
11
}

To help deal with those issues and make sure your UI code only sees what make sense for your app, Apollo Kotlin offers three tools:

• Error aware parsing
• @catch
• @semanticNonNullField

These tools change effectively the GraphQL default from "handle every field error" to "opt-in the errors you want to handle".

Nullability in Apollo Kotlin

Error aware parsing

With error aware parsing, the errors are detected at parsing time, so you don't have to look them up in the errors array. Any GraphQL error stops the parsing and you are guaranteed that response.data is actual semantic data and does not contain any error.

In order to opt-in error aware parsing, create an extra.graphqls file next to your schema and import the @catch directive:

1
# Import the `@catch` directive definition. 
2
# When it is imported, parsers generate extra code to deal with errors.
3
extend schema @link(
4
  url: "https://specs.apollo.dev/nullability/v0.3", 
5
  import: ["@catch", "CatchTo"]
6
)

And choose your default error handling. You can choose to coerce errors to null, like the current GraphQL default:

1
# Coerce errors to null by default. Partial data is returned. This partial data may contain errors that need to be checked
2
# against the `errors` array
3
extend schema @catch(to: NULL)

Or re-throw errors:

1
# Errors stop the parsing. The data never contains error. Use `@catch` in operations to let partial data through
2
extend schema @catch(to: THROW)

In the @catch(to: THROW) mode, the parsing stops at the first GraphQL error and the whole query is failed. In the example above:

1
{
2
  "data": {
3
    "user": {
4
      "id": "1001",
5
      "name": null,
6
      "avatarUrl": "https://example.com/pic.png"
7
    }
8
  },
9
  "errors": [
10
    {
11
      "message": "Cannot resolve user.name",
12
      "path": ["user", "name"]
13
    }
14
  ]
15
}

response.data is null and response.exception is an instance of ApolloGraphQLException:

1
println(response.data) // null
2
println(response.exception) // ApolloGraphQLException

This default makes it easy to handle errors as they are all handled at parsing time. Any null in the response is guaranteed to be a semantic null and not an error, and you should probably handle it.

Sometimes failing the whole query feels a bit overkill though. For those cases, you can handle errors with @catch.

Handle errors and receive partial data with @catch

In some cases, you might want to display the data returned from the server, even if it is partial.

To do so, catch GraphQL errors using the @catch directive:

1
query GetUser {
2
  user {
3
    id
4
    # map name to FieldResult<String?> instead of stopping parsing
5
    name @catch
6
    avatarUrl
7
  }
8
}

Instead of failing the whole query, the name field is now generated as a FieldResult<String?> class that can contain either a nullable value or an error:

1
// name does not have a value
2
println(response.data?.user?.name?.valueOrNull) // null
3
// but name has an error
4
println(response.data?.user?.name?.graphQLErrorOrNull?.message) // "Cannot resolve user.name"
5
// partial data is available
6
println(response.data?.user?.id) // "42"
7
// exception is null
8
println(response.exception) // null

For fields of List type, @catch applies only to the first level. If you need to apply it to a given level, use the levels argument:

1
query GetUser {
2
  user {
3
    # socialLinks fails the operation on error 
4
    # socialLinks[0], socialLinks[1], socialLinks[2], etc... are mapped to FieldResult classes
5
    socialLinks @catch(levels: [1])
6
  }
7
}

For fields of composite type, @catch catches any nested error:

1
query GetUser {
2
  # catch errors on user and any nested field 
3
  user @catch(to: RESULT) {
4
    name 
5
    avatarUrl
6
  }
7
}

Response:

1
{
2
  "data": {
3
    "user": {
4
      "id": "1001",
5
      "name": null,
6
      "avatarUrl": "https://example.com/pic.png"
7
    }
8
  },
9
  "errors": [
10
    {
11
      "message": "Cannot resolve user.name",
12
      "path": ["user", "name"]
13
    }
14
  ]
15
}

data.user is a FieldResult<User>:

1
// user is a FieldResult<User> that contains the name error
2
println(response.data?.user?.graphQLErrorOrNull?.message) // "Cannot resolve user.name"

Handle semantic non-null with @semanticNonNullField

Even with automatic detection of errors and handling of partial data like described above, you still have to check for null in your UI code. This is because of the same reason that GraphQL by default recommends nullable fields. Your backend team has no other choice than make a field nullable if it can fail.

But a field like 'User.name' is semantically non-null: it should never be null, except when something goes really wrong.

In those cases, you can mark a field as "semantic non-null" and the Apollo Kotlin compiler will generate it as non-nullable even though it is nullable in the server schema. To do so, add @semanticNonNullField to your extra.graphqls file:

1
# extra.graphqls
2

3
# Import the `@semanticNonNull` directive definition in addition to `@catch` and `CatchTo`. 
4
extend schema @link(
5
  url: "https://specs.apollo.dev/nullability/v0.3", 
6
  import: ["@catch", "CatchTo", "@semanticNonNullField"]
7
)
8

9
# mark User.name as semantic non-null
10
extend type User @semanticNonNullField(name: "name")

name is now a non-null Kotlin types:

1
class User(
2
    val id: String,
3
    // name is non-null here
4
    val name: String,
5
    val avatarUrl: String?,
6
)

If, by any chance, an error happens that you still want to handle on that field, you can use @catch to map name to a FieldResult<String> property containing a non-null value or an error.

1
user.name.valueOrNull // "Luke Skywalker"
2
user.name.graphQLErrorOrNull // null

Similarly to @catch, @semanticNonNullField supports a levels argument for lists:

1
# User.friends is generated a nullable
2
# User.friends[0], User.friends[1], User.friends[2], etc.. is generated a non-null
3
extend type User @semanticNonNullField(name: "friends", levels: [1])

Migrate progressively with @ignoreErrors

@ignoreErrors is an operation directive that disables error aware parsing for a specific operation:

1
"""
2
Never throw on errors.
3

4
This is used for backward compatibility for clients where this was the default behaviour.
5
"""
6
directive @ignoreErrors on QUERY | MUTATION | SUBSCRIPTION

To enable it, import it like @catch, CatchTo and @semanticNonNullField:

1
extend schema @link(
2
  url: "https://specs.apollo.dev/nullability/v0.3",
3
  import: ["@catch", "CatchTo", "@semanticNonNullField", "@ignoreErrors"]
4
)

Enabling error aware parsing and adding @ignoreErrors to all your operations is a no-op. You can then remove @ignoreErrors from your operations progressively.

Decision flowchart

Different teams have different needs:

• Some teams have a schema where a lot of fields are non-null already and might know from their backend team that all the nullable ones are semantic nulls. For those teams, there is little value in using @catch or @semanticNonNullField.
• Other teams have a schema where fields are all nullable by default, according to the GraphQL best practices.
  • Some of them want to display as much data as possible always. The frontend team needs to check for errors on every field and this makes the experience very robust at the price of more complex client code.
  • Some of them want to opt-in the errors they want to handle and save the code to check every field.

Finally, some teams want to opt-in error aware parsing without breaking their existing codebase. For those cases, @ignoreErrors allows a more progressive solution.