gatsbyjs/gatsby · error · Error

${REPORTER_PREFIX} Error in custom page filter. If you've cu

Error message

${REPORTER_PREFIX} Error in custom page filter.
If you've customized your excludes you may need to provide a custom "filterPages" function in your config.
https://www.gatsbyjs.com/plugins/gatsby-plugin-sitemap/#api-reference

What it means

Thrown by gatsby-plugin-sitemap when the user-provided custom filterPages function (or its default) throws while matching a page against a custom exclude pattern. This covers the `excludes` array from the plugin config, distinct from the built-in default excludes. The message guides the user to supply a custom filterPages function because their excludes patterns likely contain values the default matcher cannot handle.

Source

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

          page
        )}`
      )
    }

    // If page is marked to be excluded via defaults there's no need to check page for custom excludes
    if (defaultFilterMatches) {
      return !defaultFilterMatches
    }

    const customFilterMatches = excludes.some(exclude => {
      try {
        return filterPages(page, exclude, {
          minimatch,
          withoutTrailingSlash,
          resolvePagePath,
        })
      } catch {
        throw new Error(
          `${REPORTER_PREFIX} Error in custom page filter.
If you've customized your excludes you may need to provide a custom "filterPages" function in your config.
https://www.gatsbyjs.com/plugins/gatsby-plugin-sitemap/#api-reference
`
        )
      }
    })

    if (customFilterMatches) {
      messages.push(
        `${REPORTER_PREFIX} Custom filtering excluded page ${resolvePagePath(
          page
        )}`
      )
    }

    return !(defaultFilterMatches || customFilterMatches)
  })

View on GitHub (pinned to 8b06340921)

Solutions

Ensure every entry in the sitemap plugin's `excludes` option is a glob string (e.g., '/admin/*'), not a RegExp or object.
Provide a custom `filterPages` function in gatsby-config.js under the sitemap plugin options to handle non-standard exclude logic.
Verify minimatch syntax — use forward-slash absolute paths starting with '/' relative to the site root.
Check the plugin options reference at the URL in the error for the expected filterPages signature.

Example fix

// before
{
  resolve: 'gatsby-plugin-sitemap',
  options: { excludes: [/^\/admin/] }
}
// after
{
  resolve: 'gatsby-plugin-sitemap',
  options: { excludes: ['/admin/*'] }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate excludes config before build
const validExcludes = pluginOptions.excludes.filter(e => typeof e === 'string')
if (validExcludes.length !== pluginOptions.excludes.length) {
  throw new Error('All sitemap excludes must be glob strings')
}

Type guard

const isGlobString = (val: unknown): val is string =>
  typeof val === 'string' && val.length > 0

Prevention

Always use glob string patterns (not RegExp) in the excludes option.
Provide a custom filterPages function when your exclude logic is non-standard.
Test exclude patterns against your actual page list before deploying.

When it happens

Trigger: The excludes.some() loop calls the configured filterPages() with each exclude entry; if an exclude is not a string/glob pattern that minimatch can process, or if the page path is malformed, the inner call throws and is caught by the bare catch which rethrows this message.

Common situations: A user configures `excludes` with a regex object or non-string value instead of a glob string, uses a glob pattern minimatch rejects, or passes excludes entries that depend on page fields that don't exist.

Related errors

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