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.