gatsbyjs/gatsby · error

Invalid plugin options for "gatsby-plugin-sitemap": "query"

Error message

Invalid plugin options for "gatsby-plugin-sitemap":
"query" must be a valid GraphQL query. Received the error "${e.message}"

What it means

Options validation for gatsby-plugin-sitemap: the user-supplied query string fails graphql parse in the .external() check of the Joi schema. The error names the parser failure, so the sitemap query in gatsby-config is invalid GraphQL.

Source

Thrown at packages/gatsby-plugin-sitemap/src/options-validation.js:50

            siteMetadata {
              siteUrl
            }
          }

          allSitePage {
            nodes {
              path
            }
          }
        }`
      )
      .external(pluginOptions => {
        const query = pluginOptions?.query
        if (query) {
          try {
            parseGraphql(query)
          } catch (e) {
            throw new Error(
              stripIndent`
        Invalid plugin options for "gatsby-plugin-sitemap":
        "query" must be a valid GraphQL query. Received the error "${e.message}"`
            )
          }
        }
      })
      .description(
        stripIndent`
        (GraphQL Query) The query for the data you need to generate the sitemap.
        It's required to get the site's URL, if you are not fetching it from \`site.siteMetadata.siteUrl\`,
        you will need to set a custom \`resolveSiteUrl\` function.
        If you override the query, you may need to pass in a custom \`resolvePagePath\` or
        \`resolvePages\` to keep everything working.
        If you fetch pages without using \`allSitePage.nodes\` query structure
        you will definately need to customize the \`resolvePages\` function.`
      ),
    excludes: Joi.array()

View on GitHub (pinned to e85d62f177)

Solutions

1. Correct the GraphQL syntax of the sitemap plugin's query option
2. Test the query in GraphiQL before putting it in gatsby-config
3. Omit query to use the default sitemap query

When it happens

Trigger: Thrown at packages/gatsby-plugin-sitemap/src/options-validation.js:50 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/50c97a407c232c32. Report an issue: GitHub.