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.
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.
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
- 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.
Links not working
1. Link Resolver
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.
3. Open in new tab option not available in Links
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.
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:
const prismicContent = data.prismic.allBlog_posts.edges 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.