Issue with Gatsby and Sanity connection, resolved with a workaround.

I feel your frustration - this is actually a common issue that trips people up! The good news is it's usually fixable with a few specific steps. Let me walk you through the most likely causes and solutions.

The Core Issue

When you see your Sanity data in the GraphQL Playground but not in Gatsby's GraphiQL, it means the gatsby-source-sanity plugin isn't successfully fetching your schema or data. Here's what's likely happening:

Most Common Solutions

1. Clear Gatsby's Cache

This is the #1 fix. Gatsby caches GraphQL schemas aggressively, and sometimes doesn't pick up changes:

gatsby clean
gatsby develop

This clears .cache and public folders and forces Gatsby to re-fetch everything from Sanity.

2. Verify Your gatsby-config.js Setup

Double-check your configuration has all required fields:

{
  resolve: 'gatsby-source-sanity',
  options: {
    projectId: 'your-project-id',
    dataset: 'production', // or your dataset name
    token: process.env.SANITY_TOKEN, // if using private dataset
    watchMode: true, // enables hot-reloading in dev
    overlayDrafts: true, // if you want to see drafts
  }
}

3. API Version Parameter

Add an apiVersion to your config - this is often the culprit:

{
  resolve: 'gatsby-source-sanity',
  options: {
    projectId: 'your-project-id',
    dataset: 'production',
    apiVersion: '2023-05-03', // Use today's date in YYYY-MM-DD format
    // ... other options
  }
}

4. Check Your Token Permissions

If you're using a token (required for private datasets or overlayDrafts):

• Go to manage.sanity.io
• Navigate to your project → API → Tokens
• Ensure your token has Viewer or Editor permissions
• Make sure the token is actually being read (check console.log(process.env.SANITY_TOKEN) temporarily)

5. Verify GraphQL API Deployment

Run this in your Sanity studio folder:

sanity graphql deploy

Then check if the deployment was successful by visiting your GraphQL Playground at https://YOUR-PROJECT-ID.api.sanity.io/v1/graphql/DATASET/default

6. Enable Debug Logging

Set this environment variable to see what gatsby-source-sanity is doing:

SANITY_DEBUG=true gatsby develop

This will show you detailed logs about what the plugin is fetching and any errors it encounters.

Understanding the typePrefix Option

If you're seeing different type names than expected, check if you have a typePrefix option in your config. By default, Gatsby prefixes all Sanity types with "Sanity" (hence allSanityHomepage). If you've changed this, your queries would need to match.

Deployment-Specific Issue

Since you mentioned this happened when launching to Netlify, check:

• Are your environment variables set in Netlify's dashboard? (Settings → Environment variables)
• Is your SANITY_TOKEN present in Netlify if you're using overlayDrafts or a private dataset?
• Try triggering a fresh deploy after clearing Gatsby's cache in your repo

Quick Diagnostic Checklist

1. ✅ Run gatsby clean && gatsby develop
2. ✅ Add apiVersion to gatsby-config.js
3. ✅ Verify token exists and has correct permissions
4. ✅ Run sanity graphql deploy in studio folder
5. ✅ Check environment variables in Netlify
6. ✅ Try SANITY_DEBUG=true gatsby develop to see errors

The fact that your GraphQL Playground works means your Sanity setup is fine - this is purely a Gatsby-side connection issue. Start with the cache clear and apiVersion addition, as those fix 90% of these cases.

Let us know if you're still stuck after trying these steps!