Troubleshooting

Here you can find help solving some of the most common issues when using Prismic in your Gatsby website.


Missing html or raw values

Problem: You're trying to query a Rich Text field and can't find the raw and html tags.

It's likely due to the fact that Gatsby isn't reading the field as a Rich Text field. This happens when the JSON schema isn’t correctly updated in the project, or there is an issue with the field name, such as a hyphen/dash ( - ).

Solution: Avoid using hyphens/dashes ( - ) in the API IDs of the fields and change the existing ones.


Null Document Data (Links)

Problem: Your link's document content returns null.

A common reason why this happens is because the Custom Type name has a hyphen/dash ( - ).

Solution: Make sure you're correctly declaring the Custom Types in the gatsby-config.js. The Custom Type name in schema should be declared under single quotes, like in the following example:

Copy
schemas: { 'home_-_page': require('./src/schemas/home_-_page'), }

Test queries in the GraphQL Browser are not working.

If you're using the browser tool to test your queries, you need to make sure you are using 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 schema and won't work to test your Gatsby queries.


Update the Schema

Problem: You can't find changes made inside your Prismic repository: Custom types / Slices / Fields / Documents.

It's probably because the schema definition is outdated.

Solution: Run the gatsby cli command to clear the cache, then re-run your project. You can refresh and test the queries again in the Playground to see the updated schema:

Copy
gatsby clean

Alternatively you can delete the cache manually.


Not getting the complete list of documents

Problem: You only get 20 documents.

The API is designed to return a maximum of 20 documents per request. There is no way to increase this number.

Solution: You'll need to implement Pagination to retrieve more than the initial 20 documents.


Links not working

3. Open in new tab option not available in Links

Problem: The checkbox in Prismic allows Link fields to target: "_blank" is not yet available in the GraphQL schema.

Solution: 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.


Still not working?

If you haven’t found a solution, you can reach out to us in the Prismic community forum.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.