gatsbyjs/gatsby · error

Error resolving Pages

Error message

${REPORTER_PREFIX} Error resolving Pages

What it means

In gatsby-plugin-sitemap's onPostBuild (gatsby-node.js:36-38), the plugin calls resolvePages(queryRecords) wrapped in Promise.resolve. If the user-provided (or default) resolvePages function throws synchronously or returns a rejected promise, the .catch handler calls reporter.panic. resolvePages is expected to return an array of page objects from the GraphQL query data.

Solutions

  1. Check the err in the panic output for the specific thrown error
  2. If using a custom resolvePages, ensure it handles the query result shape returned by your query option
  3. Add null/undefined guards inside resolvePages: if (!data?.allSitePage?.nodes) return []
  4. Test resolvePages independently by logging the queryRecords shape

Example fix

// before: custom resolvePages accessing undefined
resolvePages: (data) => data.allSitePage.nodes.map(node => ({
  path: node.path,
  // if data.allSitePage is undefined, this throws
})),

// after: add guards
resolvePages: (data) => {
  if (!data?.allSitePage?.nodes) return []
  return data.allSitePage.nodes.map(node => ({
    path: node.path,
  }))
},
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate resolvePages output before passing to the plugin
const testData = { allSitePage: { nodes: [{ path: '/' }] } }
try {
  const result = resolvePages(testData)
  if (!Array.isArray(result)) {
    throw new Error('resolvePages must return an array')
  }
} catch (e) {
  console.error('resolvePages has a bug:', e.message)
}

Type guard

function isValidPagesResult(result: unknown): result is Array<Record<string, unknown>> {
  return Array.isArray(result) && result.every(item =>
    typeof item === 'object' && item !== null
  )
}

Try / catch

// Make resolvePages defensive:
resolvePages: (data) => {
  try {
    return data?.allSitePage?.nodes ?? []
  } catch (err) {
    console.error('resolvePages failed:', err)
    return []
  }
}

Prevention

When it happens

Trigger: A custom resolvePages function throws by accessing an undefined property (e.g. data.allSitePage.nodes when the query shape differs). The default resolvePages receives null/undefined queryRecords because the query returned no data. Logic error inside a custom resolvePages implementation.

Common situations: Custom resolvePages that doesn't match the actual GraphQL query output shape. Query returns empty data. Plugin options changed query but not resolvePages (or vice versa).

Related errors

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

Appendix: source

Thrown at packages/gatsby-plugin-sitemap/src/gatsby-node.js:37

    serialize,
  }
) => {
  const { data: queryRecords, errors } = await graphql(query)

  // resolvePages and resolveSiteUrl are allowed to be sync or async. The Promise.resolve handles each possibility
  const siteUrl = await Promise.resolve(resolveSiteUrl(queryRecords)).catch(
    err => reporter.panic(`${REPORTER_PREFIX} Error resolving Site URL`, err)
  )

  if (errors) {
    reporter.panic(
      `Error executing the GraphQL query inside gatsby-plugin-sitemap:\n`,
      errors
    )
  }

  const allPages = await Promise.resolve(resolvePages(queryRecords)).catch(
    err => reporter.panic(`${REPORTER_PREFIX} Error resolving Pages`, err)
  )

  if (!Array.isArray(allPages)) {
    reporter.panic(
      `${REPORTER_PREFIX} The \`resolvePages\` function did not return an array.`
    )
  }

  reporter.verbose(
    `${REPORTER_PREFIX} Filtering ${allPages.length} pages based on ${excludes.length} excludes`
  )

  const { filteredPages, messages } = pageFilter(
    {
      allPages,
      filterPages,
      excludes,
    },

View on GitHub (pinned to 8b06340921)