This page has moved to the Gatsby monorepo!
Hi there! 👋 thank you so much for being a beta/alpha tester of this plugin! You've helped us bring a much more stable WordPress integration to Gatsby and we're very thankful for that!
We've shipped this plugin as gatsby-source-wordpress@4.0.0.
gatsby-source-wordpress-experimental is now deprecated.
Please upgrade by npm/yarn installing the latest version of the stable plugin and updating your gatsby-config.js to include the stable plugin name.
We've chosen this point to release this plugin as a stable release not because there are no bugs (all software has some bugs), but because this plugin is far more stable than the last major version of gatsby-source-wordpress.
Note that we will continue fixing Github issues you've opened in the -experimental repo - those are not forgotten and will be transferred to the Gatsby monorepo.
Thank you! 💜
If some fields are returning null or an empty array when you think they should be returning data, a few things could be at play. To debug follow these steps:
- Make the same query in Gatsby and directly to WPGraphQL using a GraphQL client app like GraphQL Playground. Do not use wp-graphiql to debug because it is authenticated and Gatsby will not be authenticated when sourcing data. Use a 3rd party GraphQL client outside of WordPress.
For example if pages weren't returning titles for some reason and the following was your query in Gatsby:
{
allWpPage {
nodes {
id
title
}
}
}Take that query and make the query directly to your WP instance GraphQL API like so:
{
pages {
nodes {
id
title
}
}
}-
Does the returned data look the same in GraphQL playground as it did in Gatsby? If it does but data should exist there is likely a bug in WPGraphQL or in a WPGraphQL extension you're using. Be sure to double check that these fields should actually be returning data and that that data isn't missing when you go to edit your post in WordPress.
-
If the returned data does not look the same, enable this plugin option in Gatsby:
{ resolve: `gatsby-source-wordpress-experimental`, options: { debug: { graphql: { writeQueriesToDisk: true, }, }, }, },
-
Run
gatsby developorgatsby buildagain. -
In your Gatsby project you will now have a directory at
your-app/WordPress/GraphQL/. Within this directory you will find a directory for each node type that is sourced from WPGraphQL for your Gatsby site. -
Find the directory of the type that returns missing data. For our example we would look in
WordPress/GraphQL/Page/ -
Within this directory there will be 3
.graphqlfiles. Open the file namednode-list-query.graphqland copy the query contained within it. -
Paste this query into GraphQL Playground and add these query variables:
{ "first": 100, "after": null } -
Execute the query
-
Does the response also have missing data?
this means you're experiencing a bug on the WPGraphQL side of things. Seek help in the WPGraphQL Slack or open an issue in the WPGraphQL Github repo, or the Github repo for the WPGraphQL extension that manages the fields you're having trouble with. To help them debug you should narrow down exactly which combination of fields in the generated query you copied is causing issues. Comment out fields 1 by 1 until the problem goes away to determine which combination of fields isn't working.
Note: A common cause of this problem is that you're using ACF and you've named multiple fields with the same name but in different field groups. Identify conflicting field names and rename them.
This means it's a
gatsby-source-wordpress-experimentalbug. Open an issue in the Github repo.
If your build is erroring on a GraphQL error returned in the response from a GraphQL request, the terminal output will tell you which type this is. Returned GraphQL errors almost always indicate a bug on the WP side of things. To replicate the error outside of gatsby, enable the debug.graphql.writeQueriesToDisk plugin option:
{
resolve: `gatsby-source-wordpress-experimental`,
options: {
debug: {
graphql: {
writeQueriesToDisk: true,
},
},
},
},Now run gatsby develop or gatsby build again. When the process exits on your GraphQL error, take note of which GraphQL type the error was for, then open this file: your-site/WordPress/GraphQL/[TypeOfErroringQuery]/node-list-query.graphql.
Within this file will be the query made during node sourcing to fetch data from WPGraphQL into Gatsby.
You can use this query to reproduce your error message and debug your error message outside of Gatsby. If you're stuck seek help in the WPGraphQL Slack or open an issue in the WPGraphQL Github repo, or the Github repo for the WPGraphQL extension that manages the fields you're having trouble with.
If you're running into these errors during node sourcing, the plugin may be trying to fetch more data from your WordPress instance than your WP server can handle. Try lowering the schema.perPage plugin option from it's default of 100 and re-run your build process.
You can also try changing the schema.requestConcurrency option to limit the amount of GraphQL requests concurrent GraphQL requests made at any time when sourcing data from WPGraphQL. It's default is 15 concurrent requests.
Another reason this can happen is that one of your GraphQL queries causes an unrecoverable error on your WordPress server. See the section on debugging GraphQL errors for debugging steps.
If you're running into timeouts during node sourcing, it is likely that your WordPress server is limiting the number of concurrent requests to a number lower than the number of different types that this source plugin is attempting to source from your WordPress server. You can either increase the number of concurrent connections your WordPress server can handle by tuning or replacing your server, or you can lower the plugin option schema.requestConcurrency to a lower number than the number of concurrent GraphQL requests your WordPress server can handle.
To determine how many concurrent GraphQL requests your server can handle, enable verbose mode with the verbose plugin option:
{
resolve: `gatsby-source-wordpress-experimental`,
options: {
verbose: true,
},
},Then run your build again. You will see a long list of types that the source plugin is fetching from WordPress such as Page, Post, User, etc.
Notice that each of these types is reporting on the right-side how many nodes is sourced from each.
You will see that at the bottom of the list there are some types which aren't yet returning nodes.
Count upwards from the last type that seems to be frozen to the top of the list. This is the number of concurrent GraphQL requests your server can handle.
Note that GATSBY_CONCURRENCT_DOWNLOAD has been retired, now schema.requestConcurrency plugin option is used.
The main error that occurs while fetching media files is overwhelming the remote server due to too many concurrent requests. You can set the schema.requestConcurrency plugin option below it's default of 100. You will need to experiment a bit to determine what the maximum number of concurrent requests for media files your server can handle is.
Since a Previewed post might have a lot less data attached to it than what you're testing with during development, you might get errors in previews when that data is missing. You can debug your previews by running Gatsby in preview mode locally.
- Run Gatsby in refresh mode with
ENABLE_GATSBY_REFRESH_ENDPOINT=true gatsby develop - Install ngrok with
npm i -g ngrok - In a new terminal window run
ngrok http 8000 - In your WP instances GatsbyJS settings, set your Preview instance URL to
https://your-ngrok-url.ngrok.ioand your preview refresh endpointhttps://your-ngrok-url.ngrok.io/__refresh
Now when you click preview in wp-admin it will use your local instance of Gatsby. You can inspect the preview template to see which Gatsby path is being loaded in the preview iframe and open it directly to do further debugging.
You can proactively protect against broken Preview templates by using optional chaining to prevent trying to access properties on undefined.
Check in your wp-config.php to determine wether or not post revisions are disabled. Look for define( 'WP_POST_REVISIONS', FALSE ); and if you find it, remove it. This appears to be a WPGraphQL bug and we're working on fixing it. If you're interested in the status of that check wp-graphql/wp-graphql#1408.
If post revisions are enabled on your site and previews are still not working, please open a new issue.
You can enable Preview debug mode to help you debug issues with the Gatsby Preview build process. Visit the plugin options page to see how to enable this debug option. This option will log addition info to the terminal output including the contents of the webhook body that was sent to the Gatsby process, a list of the Preview change events Gatsby receives, as well as the node Preview data that was sourced during the Preview.