gatsbyjs/gatsby · error · Error

Invalid options passed to page Filter function

Error message

Invalid options passed to page Filter function

What it means

pageFilter is the top-level sitemap filtering entry point. It requires allPages to be an array, filterPages to be a function, and excludes to be an array. If any of these contracts is violated, it throws 'Invalid options passed to page Filter function'. This is almost always a plugin-internal invocation error rather than direct user input, because the plugin assembles these from its options.

Source

Thrown at packages/gatsby-plugin-sitemap/src/internals.js:159

  }
}

const defaultExcludes = [
  `/dev-404-page`,
  `/404`,
  `/404.html`,
  `/offline-plugin-app-shell-fallback`,
]

export function pageFilter({ allPages, filterPages, excludes }) {
  const messages = []

  if (
    !Array.isArray(allPages) ||
    typeof filterPages !== `function` ||
    !Array.isArray(excludes)
  ) {
    throw new Error(`Invalid options passed to page Filter function`)
  }

  // TODO we should optimize these loops
  const filteredPages = allPages.filter(page => {
    const defaultFilterMatches = defaultExcludes.some(exclude => {
      try {
        const doesMatch = defaultFilterPages(page, exclude, {
          minimatch,
          withoutTrailingSlash,
          resolvePagePath,
        })

        return doesMatch
      } catch {
        throw new Error(`${REPORTER_PREFIX} Error in default page filter`)
      }
    })

View on GitHub (pinned to 8b06340921)

Solutions

1. Ensure options.exclude is an array of strings: exclude: ['/secret'].
2. Ensure options.filterPages, if provided, is a function: filterPages: (page, excludes) => boolean.
3. Update gatsby-plugin-sitemap to the latest version compatible with your gatsby.
4. If the error persists, check that no other plugin is mangling the pages array in onCreatePage/createsPages.

Example fix

// before
{
  resolve: `gatsby-plugin-sitemap`,
  options: { exclude: `/secret`, filterPages: `glob` }
}

// after
{
  resolve: `gatsby-plugin-sitemap`,
  options: {
    exclude: [`/secret`],
    filterPages: (page, excludedRoutes) => !excludedRoutes.includes(page.path)
  }
}

function validateSitemapOptions({ allPages, filterPages, excludes }) {
  if (!Array.isArray(allPages)) throw new Error('allPages must be an array');
  if (typeof filterPages !== 'function') throw new Error('filterPages must be a function');
  if (!Array.isArray(excludes)) throw new Error('excludes must be an array');
}

function isValidPageFilterArgs({ allPages, filterPages, excludes }) {
  return Array.isArray(allPages) &&
    typeof filterPages === 'function' &&
    Array.isArray(excludes);
}

When it happens

Trigger: Plugin option misconfiguration: options.filterPages set to a non-function (string, object); options.exclude set to a non-array (string, object); or the Gatsby pages collection not being an array due to an upstream node issue. Also reachable if a custom integration calls pageFilter directly with wrong shapes.

Common situations: Setting options.filterPages to a glob string by mistake; passing options.exclude as a single string instead of an array; version mismatch between gatsby-plugin-sitemap and gatsby core where the pages shape changed; plugin loaded twice with conflicting configs.

Related errors

• You've passed something other than string to the exclude arr
• Neither "cache" or "getCache" was passed. getCache must be f
• createNodeId must be a function, was ${typeof createNodeId}
• createNode must be a function, was ${typeof createNode}
• Neither "cache" or "getCache" was passed. getCache must be f

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