gatsbyjs/gatsby · error · Error

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

Error message

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

What it means

Thrown during plugin options validation (via pluginOptionsSchema's .external() check) when the `query` option provided to gatsby-plugin-sitemap fails GraphQL parsing. The plugin uses graphql's parseGraphql to validate that the user-supplied query is syntactically valid GraphQL before runtime.

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 8b06340921)

Solutions

1. Validate the query string in a GraphQL IDE (GraphiQL) against your schema to find the syntax error.
2. Ensure the query contains valid GraphQL structure: query { ... } or { ... } with balanced braces.
3. Start from the default query in the plugin docs and add fields incrementally.
4. Check for stray template literal interpolation or unescaped quotes inside the query string.

Example fix

// before
options: { query: '{ site { siteMetadata { siteUrl } allSitePage { nodes { path ' } } }' }
// after
options: { query: '{ site { siteMetadata { siteUrl } } allSitePage { nodes { path } } }' }

// Validate the GraphQL query before passing to plugin config
const { parse } = require('graphql')
try {
  parse(sitemapOptions.query)
} catch (e) {
  throw new Error(`Sitemap query is invalid GraphQL: ${e.message}`)
}

try {
  parseGraphql(pluginOptions.query)
} catch (e) {
  // handle before build: fix query or remove the option to use default
}

When it happens

Trigger: The .external() validator runs parseGraphql(pluginOptions.query); a syntax error, missing closing brace, invalid field name, or non-GraphQL string causes parse to throw, and the catch wraps e.message into this error.

Common situations: User copies a partial or malformed GraphQL query into gatsby-config, forgets a closing brace, uses a fragment without defining it, or pastes plain SQL/REST text by mistake.

Related errors

• Error executing the GraphQL query inside gatsby-plugin-sitem
• ${REPORTER_PREFIX} Error in custom page filter. If you've cu
• The "layout" argument is required for "${source.url}"
• Either the "width" or "height" argument is required f
• Cannot specify both JPG and PNG formats

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/417be05cae696602. Report an issue: GitHub.