Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Link
✓ import { Link } from 'gatsby'
✗ import Link from 'gatsby'
Used for client-side navigation between Gatsby pages. Always a named import.
graphql
✓ import { graphql } from 'gatsby'
✗ const graphql = require('gatsby').graphql
The `graphql` tag is primarily used for page queries and static queries. It must be imported from 'gatsby'.
useStaticQuery
✓ import { useStaticQuery } from 'gatsby'
✗ import useStaticQuery from 'gatsby/use-static-query'
A React Hook for querying data in any component, not just pages. Available since Gatsby v4. Use `import { useStaticQuery } from 'gatsby'`.
Head
✓ import { Head } from 'gatsby'
✗ import Head from 'gatsby/head'
The Gatsby Head API (since v4) allows managing the document `<head>` from components. It's a named export.
This example demonstrates a basic Gatsby page component (`index.tsx`) using a GraphQL page query to fetch `siteMetadata` and rendering it. It also shows client-side navigation with `Link` and head management with `Head`.
import React from 'react';
import { graphql, Link, Head } from 'gatsby';
interface SiteMetadata {
title: string;
description: string;
}
interface DataProps {
site: {
siteMetadata: SiteMetadata;
};
}
const HomePage: React.FC<{ data: DataProps }> = ({ data }) => {
const { title, description } = data.site.siteMetadata;
return (
<div>
<Head>
<title>{title}</title>
<meta name="description" content={description} />
</Head>
<h1>Welcome to {title}</h1>
<p>{description}</p>
<p>
Explore the <Link to="/blog">Blog</Link> or view the{' '}
<a href="https://www.gatsbyjs.com" target="_blank" rel="noopener noreferrer">
Gatsby documentation
</a>
.
</p>
</div>
);
};
export default HomePage;
export const query = graphql`
query SiteInfo {
site {
siteMetadata {
title
description
}
}
}
`;
// To make this query work, ensure you have siteMetadata defined in your gatsby-config.ts:
// module.exports = {
// siteMetadata: {
// title: `My Awesome Gatsby Site`,
// description: `A sample Gatsby project showcasing site features.`,
// siteUrl: `https://www.example.com`,
// },
// plugins: [],
// };
gatsby --version
Debug
Known issues
breakingGatsby 5 requires Node.js version `>=18.0.0 <26`. Using older or incompatible Node.js versions can lead to installation failures and runtime errors.fixUpgrade your Node.js environment to a compatible version (e.g., Node.js 18, 20, 22, or 24 LTS). Refer to Gatsby's official documentation for current recommendations.
affects: <5.0.0
gotchaWhen upgrading `gatsby-source-shopify` to version 9.0.0, there is a possibly breaking change due to an upgrade from Shopify API version 2022-04 to 2024-04. This might affect how data is structured or exposed.fixReview your GraphQL queries and data consumption logic after upgrading `gatsby-source-shopify` to ensure compatibility with the new Shopify API version. Check the `gatsby-source-shopify` changelog for specific migration details.
affects: >=9.0.0 of gatsby-source-shopify
gotchaVersions of Gatsby prior to 5.16.1 experienced regressions with the Gatsby Head API, specifically where `<title>` elements might not correctly update `document.title`.fixUpgrade to Gatsby 5.16.1 or newer to resolve issues with the Gatsby Head API and ensure `<title>` updates `document.title` as expected.
affects: >=5.0.0 <5.16.1
gotchaGatsby 5.16.0 introduced official support for React 19. While Gatsby aims for forward compatibility, specific plugins or custom components might require updates to function correctly with React 19.fixEnsure you are on Gatsby 5.16.0 or newer for official React 19 support. Thoroughly test your site and third-party plugins after upgrading React to version 19.
affects: <5.16.0
gotchaSecurity vulnerabilities in transitive dependencies like `qs` (via `body-parser`) and `multer` have been addressed in recent patches. Older Gatsby installations might be susceptible.fixRegularly update your `gatsby` package and run `npm audit fix` or `yarn audit` to ensure all dependencies are up-to-date with known security fixes. Specifically, Gatsby 5.14.4 fixed `multer` and 5.16.0 fixed `body-parser`.
affects: <5.14.4, <5.16.0
Errors
Common errors & fixes
error glob@11.0.3: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"
A dependency in your project (likely a transitive one) requires a newer Node.js version than currently installed, or Gatsby itself is enforcing a minimum Node.js version.
fixUpdate your Node.js installation to version 20 or 22 (or higher compatible versions). Gatsby 5 requires Node.js >=18.0.0 <26.
ReferenceError: isNonNullType is not defined
This error occurs with `webpack>=5.99.0` due to a breaking change in webpack's internal API that Gatsby's older versions were not compatible with.
fixUpgrade Gatsby to version 5.14.2 or newer, which contains a fix for compatibility with `webpack>=5.99.0`.
Build failed due to missing or invalid GraphQL query results.
This often happens if a GraphQL query in a page or component is malformed, refers to non-existent fields, or if a source plugin failed to fetch data.
fixCheck your GraphQL queries for typos and ensure all fields exist in your GraphQL schema. Verify your `gatsby-config.js` or `gatsby-config.ts` for correct source plugin configuration and data fetching setup. Use the GraphQL Playground (`http://localhost:8000/__graphql`) to test your queries.
Audit
Dependencies
reactrequiredCore UI library for building components.
react-domrequiredProvides DOM-specific rendering methods.