Gatsby "GraphQL Error Unknown field" on build in CI

By Daniel Zoghalchali·Latchkey

Gatsby builds its GraphQL schema by inferring types from the data that sourced at build time. A query asks for a field that is not in that schema, so the build fails before generating pages.

What this error means

gatsby build stops with "GraphQL Error Unknown field 'X' on type 'Y'" pointing at a page query or static query, often after a content or plugin change.

GraphQL Error Unknown field 'frontmatter' on type 'File'.

  file: /home/runner/work/site/site/src/pages/blog.js
  > 12 |     allFile { nodes { frontmatter { title } } }

Common causes

No data sourced that field, so it was never inferred

If no node carries the field at build time (for example an empty content directory in CI), the schema lacks it and the query is invalid.

A source or transformer plugin is missing or misconfigured

The plugin that would add the field (gatsby-transformer-remark, gatsby-source-filesystem) is absent or points at the wrong path in CI.

How to fix it

Ensure the data exists when the schema is built

1. Confirm the content directory is present and populated in the CI checkout.
2. Verify the source/transformer plugin is installed and configured for that path.
3. Re-run the build so the field is inferred and the query resolves.

{
  resolve: 'gatsby-source-filesystem',
  options: { name: 'blog', path: `${__dirname}/content/blog` },
}

Define the schema explicitly so it is stable

Use createTypes in gatsby-node to declare the field, so a query never depends on whether sample data happened to include it.

exports.createSchemaCustomization = ({ actions }) => {
  actions.createTypes(`type Frontmatter { title: String }`);
};

How to prevent it

• Declare schema types explicitly so queries do not rely on inference.
• Make sure all content is checked out before building.
• Keep source and transformer plugins installed and configured in CI.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation