Apollo GraphQL Federation Schema Validation Error [Solved!]

This is the error I’ve bumped into while working through the example for Apollo’s GraphQL Federation when setting up a subgraph API. I’ve tried several things to resolve this error including changing versions for the GraphQL library in use but that hasn’t fixed it. I’ve also got this now on MacOS, Linux, and Windows so it isn’t something odd about the environment.

๏ฃฟ ~/Codez/AppoloFederationCore-v2/ [main] node index.js
        throw new GraphQLSchemaValidationError_1.GraphQLSchemaValidationError(errors);

GraphQLSchemaValidationError: Unknown directive "@entity".
    at buildSchemaFromSDL (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/apollo-graphql/lib/schema/buildSchemaFromSDL.js:50:15)
    at buildSubgraphSchema (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/@apollo/subgraph/dist/buildSubgraphSchema.js:26:58)
    at Object.<anonymous> (/Users/adronhall/Codez/AppoloFederationCore-v2/index.js:29:11)
    at Module._compile (node:internal/modules/cjs/loader:1095:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1124:10)
    at Module.load (node:internal/modules/cjs/loader:975:32)
    at Function.Module._load (node:internal/modules/cjs/loader:816:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:79:12)
    at node:internal/main/run_main_module:17:47 {
  errors: [
    GraphQLError [Object]: Unknown directive "@entity".
        at Object.Directive (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/graphql/validation/rules/KnownDirectivesRule.js:56:29)
        at Object.enter (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/graphql/language/visitor.js:323:29)
        at visit (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/graphql/language/visitor.js:243:26)
        at Object.validateSDL (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/graphql/validation/validate.js:92:22)
        at buildSchemaFromSDL (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/apollo-graphql/lib/schema/buildSchemaFromSDL.js:48:31)
        at buildSubgraphSchema (/Users/adronhall/Codez/AppoloFederationCore-v2/node_modules/@apollo/subgraph/dist/buildSubgraphSchema.js:26:58)
        at Object.<anonymous> (/Users/adronhall/Codez/AppoloFederationCore-v2/index.js:29:11)
        at Module._compile (node:internal/modules/cjs/loader:1095:14)
        at Object.Module._extensions..js (node:internal/modules/cjs/loader:1124:10)
        at Module.load (node:internal/modules/cjs/loader:975:32)

The code I’m running is the happy path code offered in the docs.

const { ApolloServer, gql } = require('apollo-server');
const { buildSubgraphSchema } = require('@apollo/subgraph');

const typeDefs = gql`
  type Query {
    me: User

  type User @entity @key(fields: "id") {
    id: ID!
    username: String

const resolvers = {
  Query: {
    me() {
      return { id: "1", username: "@ava" }
  User: {
    __resolveReference(user, { fetchUserById }){
      return fetchUserById(user.id)

const server = new ApolloServer({
  schema: buildSubgraphSchema([{ typeDefs, resolvers }])

server.listen(4001).then(({ url }) => {
    console.log(`๐Ÿš€ Server ready at ${url}`);

Anybody seen this? Got a fix? Do I need to add the @entity directive myself? Whatever the case the I think the documentation should point out the dependency needed if it’s just a dependency, but this reliably breaks just following the happy path.


Will update this post with the resolution as I dig through troubleshooting. ๐Ÿ‘๐Ÿป

Click to read a full size image of the response.

UPDATE: Dec 3rd, 2021.

It looks like the docs were just updated incorrectly when posted and the entity directive isn’t ready for v2 just yet. Removing this directive resolves the error and we’ll need to wait until it’s added in a subsequent iteration for that capability.

Stephen Barlow (@barlow_vo) from Apollo responded via the Twitters, but also added a link to the roadmap for federation.

Beyond CRUD n’ Cruft Data-Modeling

I dig through a lot of internet results and blog entries that show CRUD data modeling all the time. A lot of these blog entries and documentation are pretty solid. Unfortunately, rarely do we end up with data that is accurately or precisely modeled the way it ought to be or the way we would ideally use it. In this post I’m going to take some sample elements of data and model it out for various uses. Then reconstitute that data into different structures for various uses within microservices, loading, reading, both in normalized form and denormalized form.

The Domain: Railroad Systems & Services

The domain I chose for this particular example is the entire global spectrum of rail services. Imagine if you would a system that can track all the trains in the world, or even just the trains in a particular area of the world, like the United States. In the United States the trains can be broken down into logical structures of data for various things like freight trains and passenger trains. Trains operated under a particular operator like Amtrak, Union Pacific, or Norfolk Southern, and their respective consists that the train is made up of. Let’s get into some particular word definitions to fully detail this domain. Continue reading “Beyond CRUD n’ Cruft Data-Modeling”