Issues with Gatsby queries

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

Are your Gatsby Prismic queries not working? Follow this common issues list to find a solution to get them up and running again.

Test queries in the GraphQL Browser are not working

1. Make sure you're using the correct Browser

If you're using the browser tool to test your queries, you need to make sure that you are using the correct one: the built-in Gatsby Playground.

The built-in Gatsby Playground is a tool in which you can test your queries. It's accessible when running your development server on http://localhost:8000/__graphql.

Learn more about the GraphQL Playground.

Prismic also has The GraphQL API Explorer. This is meant to test queries when working with GraphQL, but not for a Gatsby website. The schema definition is different from the Gatsby GraphQL API and won't work to test your Gatsby queries.

2. Update the Schema

If you are querying new Custom types / Slices / Fields and your project can't find them it's probably because the schema definition it is outdated.

Run the gatsby cli command: gatsby clean to clear the cache, then re-run and refresh the Playground to see the updated schema. Alternatively you can delete the cache manually.

Updated / New items on the Prismic repository aren't showing in the response

When you make a change inside your Prismic repository, you'll need to delete the Gatsby project's cache and rebuild the site. When you rebuild, you will then get the updated version of the schema from Prismic. This will include any changes in:

  • Custom types
  • Fields
  • Slices
  • Documents
  • Content in the fields

To clear the cache, run the gatsby cli command: gatsby clean (Alternatively you can delete the cache manually). Then rebuild the site and you should see the updated schema. You should also then see the updated content.

Not getting the complete list of documents

The API is designed to return a maximum of 20 documents per request. There is no way to increase this number, so you'll need to implement Pagination to retrieve more than the initial 20 documents.

If you're working with Gatsby Links you need to configure a Link resolver and then add it to the Links when rendering them in order to make them work. You can read more about this on the Link Resolving page.

2. Multi-language routes

When working with a multi-language project need to pass the Alternate Languages to the Link Resolver when rendering Links. Read to learn how to query by language and how to render alternate languages.

The checkbox in Prismic which allows Link fields to have a target: "_blank" is not yet available in the GraphQL schema. In order to have links open in new tabs, you'll need to create an HTML Serializer that will add the target="_blank" attribute to your links.

Also Gatsby Link is used only for internal routing. For external links that open in a new window you should use anchor tags.

Cannot read property 'value' of undefined

If you have configured the plugin to enable Previews you will need to add a validation just before saving and rendering the retrieved data. This check will prevent your application from breaking during the website build.

You'll need to ensure that the retrieved data response is valid and if not, return null. This example shows how it can be done:

Copy
const prismicContent = data.prismic.allBlog_posts.edges[0]
if (!prismicContent) return null
const document = prismicContent.node

Still not working?

If you haven’t found a solution by the end of this article you can reach out to us through the Prismic community forum.