gatsbyjs/gatsby · error

Since Gatsby v4+ you cannot use the ${typeName}.beforeChange

Error message

Since Gatsby v4+ you cannot use the ${typeName}.beforeChangeNode option as a function. Please make the option a relative or absolute path to a JS file where the beforeChangeNode fn is the default export.

What it means

Error "Since Gatsby v4+ you cannot use the ${typeName}.beforeChangeNode option as a function. Please make the option a relative or absolute path to a JS file where the beforeChangeNode fn is the default export." thrown in gatsbyjs/gatsby.

Source

Thrown at packages/gatsby-source-wordpress/src/steps/process-and-validate-plugin-options.ts:100

    name: `Require beforeChangeNode type setting functions by absolute or relative path`,
    test: ({ userPluginOptions }: IProcessorOptions): boolean =>
      !!userPluginOptions?.type,
    processor: ({
      helpers,
      userPluginOptions,
    }: IProcessorOptions): IPluginOptions => {
      // This is the Gatsby store, so we don't access it as getStore()
      const gatsbyStore = helpers.store.getState()
      const typeSettings = Object.entries(userPluginOptions.type)

      typeSettings.forEach(([typeName, settings]) => {
        const beforeChangeNodePath = settings?.beforeChangeNode

        if (
          usingGatsbyV4OrGreater &&
          typeof beforeChangeNodePath === `function`
        ) {
          helpers.reporter.panic(
            `Since Gatsby v4+ you cannot use the ${typeName}.beforeChangeNode option as a function. Please make the option a relative or absolute path to a JS file where the beforeChangeNode fn is the default export.`
          )
        }

        if (!beforeChangeNodePath || typeof beforeChangeNodePath !== `string`) {
          return
        }

        try {
          const absoluteRequirePath: string | undefined = path.isAbsolute(
            beforeChangeNodePath
          )
            ? beforeChangeNodePath
            : require.resolve(
                path.join(gatsbyStore.program.directory, beforeChangeNodePath)
              )

          const beforeChangeNodeFn = require(absoluteRequirePath)

View on GitHub (pinned to 8b06340921)

Solutions

1. Move the beforeChangeNode function into a separate JS file with a default export.
2. Set the option to a relative or absolute path to that file instead of an inline function.

When it happens

Trigger: Thrown at packages/gatsby-source-wordpress/src/steps/process-and-validate-plugin-options.ts:100 when the library encounters an invalid state.

Common situations: Occurs when a beforeChangeNode option is passed as a function in Gatsby v4+. Move the function into a JS file and set the option to the file path so it can run in a worker.

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