8. Build check errors
6m

Overview

We've seen how and work in our development flow and what happens when the process goes smoothly without any errors. It's time to tackle what happens in the not-so-happy path, when changes to a result in composition errors.

In this lesson, we will:

  • Learn about the types of errors commonly encountered in
  • Learn how to navigate errors in Studio
  • Learn how to use the @inaccessible

Updating the subgraph

Let's return to our subgraph teams, who are hard at work improving Airlock. 👩🏽‍🚀 Achilles from the Accounts team has just made a few changes to the accounts 's schema to bring visibility into a host's galactic coordinates.

In the schema, they've defined the GalacticCoordinates type the team has agreed on and included the two : latitude and longitude.

subgraph-accounts/accounts.graphql
type GalacticCoordinates {
  latitude: Float!
  longitude: Float!
}

(Did you spot the mistake already? Don't worry, we'll get to that in a moment! Remember, this lesson is about what happens when things don't work the first time!)

They've also added a new to the Host : coordinates, which returns the GalacticCoordinates type.

subgraph-accounts/accounts.graphql
type Host implements User @key(fields: "id") {
  #... other Host fields
  "Where the host is primarily located"
  coordinates: GalacticCoordinates
}

With these new schema additions in place, we're ready to help Achilles publish the changes and get this feature out into the world. Following the process we walked through in the previous lesson, the first thing on the list is using to run a local schema check.

We'll open up a new terminal window and run the rover subgraph check command against Airlock's staging , including the file path and name parameters for the accounts schema.

rover subgraph check airlock-managed-fed@staging \
  --schema "accounts.graphql" \
  --name accounts

Right away, we see that something isn't quite right! Here's the error message we see in the terminal:

Checking the proposed schema for subgraph accounts against airlock-managed-fed@staging
error[E029]: Encountered 2 build errors while trying to build subgraph "accounts" into supergraph "airlock-managed-fed@staging".


Caused by:
    Encountered 2 build errors while trying to build the supergraph.
    INVALID_FIELD_SHARING: Non-shareable field "GalacticCoordinates.latitude" is resolved from multiple subgraphs: it is resolved from subgraphs "accounts" and "listings" and defined as non-shareable in subgraph "accounts"
    INVALID_FIELD_SHARING: Non-shareable field "GalacticCoordinates.longitude" is resolved from multiple subgraphs: it is resolved from subgraphs "accounts" and "listings" and defined as non-shareable in subgraph "accounts"


    The changes in the schema you proposed for subgraph accounts are incompatible with supergraph airlock-managed-fed@staging. See https://www.apollographql.com/docs/federation/errors/ for more information on resolving build errors.

The errors indicate that the GalacticCoordinates (latitude and longitude) are resolved in both the accounts and listings , but they're defined as non-shareable in the accounts . That's the subgraph Achilles was working on!

What they missed was adding the @shareable to the type definition, so let's make sure that's included.

subgraph-accounts/accounts.graphql
type GalacticCoordinates @shareable {
  latitude: Float!
  longitude: Float!
}

Achilles makes the update to their schema, and when we run the rover subgraph check command again, we can see that this fix has resolved the error!

Checking the proposed schema for subgraph accounts against airlock-managed-fed@staging
Check Result:


Compared 1 schema changes against 13 operations
┌────────┬─────────────┬───────────────────────────────────────────────┐
│ Change │    Code     │                  Description                  │
├────────┼─────────────┼───────────────────────────────────────────────┤
│ PASS   │ FIELD_ADDED │ type `Host`: field `coordinates` added        │
└────────┴─────────────┴───────────────────────────────────────────────┘
View full details at https://studio.apollographql.com/graph/airlock-managed-fed/operationsCheck/{URL}

Achilles continues to work on their , adding the necessary and data source methods to implement their schema additions.

Adding new shared fields

Before pushing their changes up to the codebase, Achilles meets with the Airlock team and finds out that the project mockup designs have been updated! In addition to the numerical coordinates, users also want to know the local name of the location. For example, it's easier for guests to immediately understand "Planet Z" compared to "83.0405 latitude and 35.2034 longitude" (but they'll still also need to know the precise coordinates).

Achilles adds a new to the GalacticCoordinates type: nickname, which returns a String.

subgraph-accounts/accounts.graphql
type GalacticCoordinates @shareable {
  latitude: Float!
  longitude: Float!
  nickname: String
}

Awesome! This new is already being returned by the AccountsAPI service, so there are no additional changes to be made in the or data source files. Achilles is so excited to get this feature out, they forget to rerun the rover subgraph check command locally again. Instead, they push the change straight up to the GitHub codebase and create a PR. This triggers the Schema Checks job.

Oh no, the job failed!

https://github.com
Screenshot of the GitHub PR with the job failed and link to the Studio Checks page

Not to worry, that means our pipeline caught an error before it made it to production! We can investigate exactly why the job failed by following the link to Studio's Checks page embedded in the PR.

Schema checks in GraphOS

The Checks page in Studio shows us the results of the schema check so we can diagnose what went wrong.

https://studio.apollographql.com
Screenshot of the failed check in Studio Checks page

identifies the that failed to compose and indicates what went wrong in the process. And because failing means no new is generated, the continues to process requests based on its existing valid version of the supergraph schema. So even though the Accounts team's changes aren't working, clients using the staging of the don't encounter any errors! This gives the Accounts team a chance to review the error and push a fix before merging their PR.

This is the error we see:

error[E029]: Encountered 1 build error while trying to build subgraph "accounts" into supergraph "airlock-managed-fed@staging".


Caused by:
    Encountered 1 build error while trying to build the supergraph.
    SATISFIABILITY_ERROR: The following supergraph API query:
    mutation {
      updateListing(listingId: "<any id>", listing: {}) {
        listing {
          coordinates {
            nickname
          }
        }
      }
    }
    cannot be satisfied by the subgraphs because:
    - from subgraph "listings":
      - cannot find field "GalacticCoordinates.nickname".
      - cannot move to subgraph "accounts", which has field "GalacticCoordinates.nickname", because type "GalacticCoordinates" has no @key defined in subgraph "accounts".

Let's investigate the error further.

When trying to build the , we ran into a SATISFIABILITY_ERROR. This error means that our might appear compatible on the surface, but the resulting API would include at least one that the subgraphs can't satisfy.

The error message provides an example , along with two reasons why our can't satisfy it:

First, the listings can't find the GalacticCoordinates.nickname. Achilles had only added the nickname to the accounts (the subgraph their team is responsible for). The listings has no such .

Second, the listings can't pass the responsibility of resolving the nickname to the accounts , because GalacticCoordinates isn't an , it's a value type. Remember that only (types with the @key ) can resolve different across multiple .

The of a value type can differ across in some ways, but we can't omit shared . We need to add this new GalacticCoordinates.nickname to both the accounts and listings .

Note: You can learn more about the different ways shared can differ in value types in the Apollo docs on sharing types.

To incrementally add the to all of our without breaking , we can use the @inaccessible .

The @inaccessible directive

The @inaccessible is applied to a in a . Whenever it's present on a field, omits that field from the 's . This means that clients can't include the field in . This helps us incrementally add a to multiple without breaking .

Note that we only need to apply the @inaccessible to one of the where the is defined.

Let's use the @inaccessible to incrementally add the nickname to the GalacticCoordinates value type. Here's the plan:

👩🏽‍🚀 In the accounts :

  • Achilles will add the GalacticCoordinates.nickname and apply the @inaccessible .
  • We'll use our automated CI/CD process to ensure these schema additions make their way to the staging in the registry.

👩🏽‍🏫 Then, in the listings :

  • Lisa will add the GalacticCoordinates.nickname . We don't need to apply @inaccessible because it's already taken care of in the accounts .
  • We'll use our automated CI/CD process to ensure these schema additions make their way to the staging in the registry.

👩🏽‍🚀 With the new shared field added to all the subgraphs that use the value type, we can finally go back to the accounts :

  • Achilles will remove the @inaccessible from the GalacticCoordinates.nickname . This allows the field to be included in the and compose successfully, because the listings now includes the nickname .
  • We'll use our automated CI/CD process to ensure these schema additions make their way to the staging in the registry.

Let's get to it!

Using the @inaccessible directive

👩🏽‍🚀 In the accounts , Achilles will add the @inaccessible after the return type of the nickname .

subgraph-accounts/accounts.graphql
type GalacticCoordinates @shareable {
  latitude: Float!
  longitude: Float!
  nickname: String @inaccessible
}

Achilles also needs to make sure the is included in the import array at the top of the schema.

subgraph-accounts/accounts.graphql
extend schema
 @link(url: "https://specs.apollo.dev/federation/v2.7"
   import: ["@key", "@shareable", "@inaccessible"])

And that's it! With these schema changes in place, let's try running a local schema check.

rover subgraph check airlock-managed-fed@staging \
  --schema "./accounts.graphql" \
  --name accounts

In the terminal, we'll see:

Checking the proposed schema for subgraph accounts against airlock-managed-fed@staging
Compared 1 schema changes against 16 operations
┌────────┬─────────────┬────────────────────────────────────────┐
│ Change │    Code     │              Description               │
├────────┼─────────────┼────────────────────────────────────────┤
│ PASS   │ FIELD_ADDED │ type `Host`: field `coordinates` added │
└────────┴─────────────┴────────────────────────────────────────┘

Awesome, the checks pass with no errors! The addition of the nickname doesn't show up in the check because it's currently marked as @inaccessible. We'll push the changes up to GitHub and let the CI run its as well. When those pass, we can merge the PR, automatically triggering the deploy process to deploy the changes to the accounts staging environment in Heroku and the Airlock graph staging in the Apollo schema registry.

Adding the new shared field to the listings subgraph

👩🏽‍🏫 Back over to the listings , Lisa will add the nickname to the GalacticCoordinates value type.

subgraph-listings/listings.graphql
type GalacticCoordinates @shareable {
  latitude: Float!
  longitude: Float!
  nickname: String
}

This new is already being returned by the ListingsAPI service, so there are no additional changes to be made in the or data source files. We can follow the CI/CD process and get these schema changes up on the listings staging environment in Heroku and the Airlock graph staging in the Apollo schema registry!

Removing the @inaccessible directive

👩🏽‍🚀 With the GalacticCoordinates.nickname defined in every that uses the value type, Achilles is ready to remove the @inaccessible from the GalacticCoordinates.nickname .

subgraph-accounts/accounts.graphql
type GalacticCoordinates @shareable {
  latitude: Float!
  longitude: Float!
  nickname: String
}

That's it! We can follow the same CI/CD process we're used to by now and get these schema changes up on staging!

This time the schema check will show that the nickname was successfully added:

Checking the proposed schema for subgraph accounts against airlock-managed-fed@staging
Compared 1 schema changes against 16 operations
┌────────┬─────────────┬────────────────────────────────────────────────────┐
│ Change │    Code     │                    Description                     │
├────────┼─────────────┼────────────────────────────────────────────────────┤
│ PASS   │ FIELD_ADDED │ type `GalacticCoordinates`: field `nickname` added │
└────────┴─────────────┴────────────────────────────────────────────────────┘

After we've validated that everything in the staging environment looks good, we're ready to deploy to production! We've already gone over those steps in the previous lesson, so feel free to refer to that section if you need a refresher.

We've improved on our Project Galactic Coordinates by adding a familiar nickname to the coordinates. This feature is officially out in the world and ready to be used by clients!

Practice

Which of the following statements about build checks are true?

Key takeaways

  • We use the rover subgraph check command to perform locally.
  • The output of can be viewed in Studio, as well as locally with the .
  • To add a new shared to a value type, we should first apply the @inaccessible to the . Then, we can incrementally add the new field to each that defines the value type. Finally, we can remove the @inaccessible and the will be officially part of the .

Up next

In the next lesson, we'll learn about checks, and how validates proposed schema changes against the way clients have historically consumed data from the graph.

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.