Gatsby-source-sanity plugin not showing schema in GraphQL playground

I've been there! When your Sanity schema isn't showing up in Gatsby's GraphiQL explorer at http://localhost:8000/___graphql, here are the most common issues to check:

1. Verify your gatsby-config.js setup

Make sure your gatsby-source-sanity configuration has the correct project details:

{
  resolve: 'gatsby-source-sanity',
  options: {
    projectId: 'your-project-id',
    dataset: 'your-dataset',
    // Add a token if you have a private dataset
    token: process.env.SANITY_TOKEN,
    watchMode: true, // enables hot-reloading in development
    overlayDrafts: true, // if you want to preview drafts
  }
}

Double-check that your projectId and dataset name are correct. You can find these in your Sanity project settings.

2. Clear Gatsby cache and restart

Schema changes often require clearing Gatsby's cache to be picked up:

gatsby clean
gatsby develop

The gatsby clean command removes the .cache and public directories, forcing Gatsby to rebuild everything from scratch.

3. Check for published content in Sanity

Make sure you actually have published documents in your Sanity dataset. If your dataset is empty or all documents are drafts (and you haven't configured overlayDrafts), there won't be any types to show in GraphiQL. The gatsby-source-sanity plugin fetches your content from Sanity's export endpoint, so you need actual documents to create the schema.

4. Private dataset authentication

If you're using a private dataset, you must add a read-permission token to your configuration. Generate one in your Sanity project settings under API settings, then add it to your config:

token: process.env.SANITY_TOKEN

Without this token, the plugin won't be able to access your content.

5. Optional: Deploy GraphQL API for schema validation

While not required for the plugin to work, you can optionally deploy a GraphQL API to help with schema validation. From your Sanity studio folder, run:

sanity graphql deploy

If you deploy a GraphQL API, the plugin will fetch the schema definition to ensure all your types and fields are present, but the plugin works perfectly fine without this step by fetching data directly from Sanity's export endpoint.

6. Check for configuration errors

Look at your terminal where gatsby develop is running. The plugin will log any connection issues or authentication errors there. Common problems include typos in the project ID or dataset name.

Once you've gone through these steps, your Sanity types should appear in GraphiQL as allSanityPost, sanityPost, etc. The gatsby-source-sanity plugin is quite efficient—it only makes two API requests during the entire build process regardless of how many GraphQL queries you have!