gatsbyjs/gatsby · error

${REPORTER_PREFIX} The `resolvePages` function did not retur

Error message

${REPORTER_PREFIX} The `resolvePages` function did not return an array.

What it means

In gatsby-plugin-sitemap's onPostBuild (gatsby-node.js:40-44), after resolvePages completes, the plugin checks Array.isArray(allPages). If resolvePages returned something that is not an array (e.g. an object, undefined, null, a single page object), reporter.panic fires. The sitemap generation pipeline requires an array of page objects to iterate over.

Source

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

  // 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,
    },
    { reporter }
  )

  messages.forEach(message => reporter.verbose(message))

View on GitHub (pinned to 8b06340921)

Solutions

1. Ensure resolvePages returns an array: wrap the result in Array.isArray() check
2. Return data.allSitePage.nodes (the array), not data.allSitePage (the wrapper)
3. Add a default empty array fallback: return result || []

Example fix

// before: returns wrapper object, not array
resolvePages: (data) => data.allSitePage,

// after: returns the nodes array
resolvePages: (data) => data.allSitePage.nodes,

// Validate resolvePages returns an array
const result = resolvePages(queryRecords)
if (!Array.isArray(result)) {
  throw new Error(`resolvePages must return an array, got ${typeof result}`)
}

function isPageArray(value: unknown): value is Array<{ path: string }> {
  return Array.isArray(value) &&
    value.every(item =>
      typeof item === 'object' &&
      item !== null &&
      typeof (item as { path?: unknown }).path === 'string'
    )
}

// Usage in resolvePages:
resolvePages: (data) => {
  const nodes = data?.allSitePage?.nodes || []
  return isPageArray(nodes) ? nodes : []
}

When it happens

Trigger: A custom resolvePages returns a non-array value — e.g. returns the data object directly, returns a single page instead of an array, or returns undefined/null due to a logic error. The default resolvePages is overridden but the return contract is violated.

Common situations: Custom resolvePages that returns data.allSitePage (the wrapper object) instead of data.allSitePage.nodes (the array). resolvePages that returns the first page only. Missing return statement inside resolvePages.

Related errors

• ${REPORTER_PREFIX} Error resolving Pages
• Invalid plugin options for "gatsby-plugin-sitemap":
• ${REPORTER_PREFIX} Error resolving Site URL
• Error executing the GraphQL query inside gatsby-plugin-sitem
• ${REPORTER_PREFIX} Error serializing pages

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