Gatsby Sanity build fails on Netlify: "Session not found" error

The "Session not found" error you're seeing happens because gatsby-source-sanity is trying to fetch your remote GraphQL schema from Sanity, but it doesn't have proper authentication credentials. This typically occurs when building on Netlify (or other CI/CD platforms) where environment variables aren't configured correctly.

Here's what's happening: The plugin needs to authenticate with Sanity to fetch the GraphQL schema, especially if you're using a private dataset or have overlayDrafts enabled. Without proper authentication, Sanity returns a "Session not found" error.

Solution

You need to add a Sanity authentication token to your Netlify environment variables:

1. Create a read token in Sanity:

   • Go to manage.sanity.io
   • Select your project
   • Navigate to API settings
   • Under "Tokens", add a new token with read permissions

2. Add the token to Netlify:

   • Go to your Netlify site dashboard
   • Navigate to Site settings → Environment variables
   • Add a new variable with the name your plugin configuration expects (commonly SANITY_TOKEN or SANITY_AUTH_TOKEN)
   • Paste your Sanity token as the value

3. Update your gatsby-config.js to use the token:

{
  resolve: 'gatsby-source-sanity',
  options: {
    projectId: 'your-project-id',
    dataset: 'production',
    token: process.env.SANITY_TOKEN, // Make sure this matches your env var name
    watchMode: false, // Set to false for production builds
    overlayDrafts: false, // Set to false for production
  }
}

Important: Make sure the environment variable name in Netlify matches exactly what you're referencing in your gatsby-config.js file. A mismatch here (like using SANITY_AUTH_TOKEN in Netlify but referencing SANITY_TOKEN in your config) is a common cause of this error.

After adding the environment variable, trigger a new deploy in Netlify. The build should now successfully authenticate with Sanity and fetch the GraphQL schema.

If you're only seeing this error in production and not locally, it confirms that your local environment has the token set but Netlify doesn't. Also ensure you've deployed your GraphQL schema to Sanity using sanity graphql deploy from your studio folder, as gatsby-source-sanity requires a deployed schema to function.