gatsbyjs/gatsby · error

The type.MediaItem.lazyNodes option wont be supported in Ga

Error message

The type.MediaItem.lazyNodes option wont be supported in Gatsby v4+ due to query running using JS workers in PQR (Parallell Query Running). lazyNodes creates nodes in GraphQL resolvers and PQR doesn't support that.

This option works with your current version of Gatsby but will stop working in Gatsby v4+.

If you would like to prevent gatsby-source-wordpress from fetching File nodes for each MediaItem node, set the type.MediaItem.createFileNodes option to false instead.

What it means

During process-and-validate-plugin-options, the options processor for MediaItem.lazyNodes fires this warning when lazyNodes is enabled on Gatsby versions below v4. The option conflicts with Gatsby v4's Parallel Query Runner (resolvers can't create nodes there — that case panics), so on v3 the plugin warns that the option is deprecated and recommends type.MediaItem.createFileNodes: false instead for skipping File nodes.

Source

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

}

let warnedAboutMediaItemLazyNodes = false

const optionsProcessors: Array<IOptionsProcessor> = [
  {
    name: `MediaItem.lazyNodes doesn't work in Gatsby v4+`,
    test: ({ userPluginOptions }): boolean =>
      userPluginOptions?.type?.MediaItem?.lazyNodes,
    processor: ({ helpers, userPluginOptions }): IPluginOptions => {
      if (usingGatsbyV4OrGreater) {
        helpers.reporter.panic(
          formatLogMessage(
            `The type.MediaItem.lazyNodes option isn't supported in Gatsby v4+ due to query running using JS workers in PQR (Parallell Query Running). lazyNodes creates nodes in GraphQL resolvers and PQR doesn't support that.\n\nIf you would like to prevent gatsby-source-wordpress from fetching File nodes for each MediaItem node, set the type.MediaItem.createFileNodes option to false.`
          )
        )
      } else if (!warnedAboutMediaItemLazyNodes) {
        warnedAboutMediaItemLazyNodes = true
        helpers.reporter.warn(
          formatLogMessage(
            `\nThe type.MediaItem.lazyNodes option wont be supported in Gatsby v4+ due to query running using JS workers in PQR (Parallell Query Running). lazyNodes creates nodes in GraphQL resolvers and PQR doesn't support that.\n\nThis option works with your current version of Gatsby but will stop working in Gatsby v4+.\n\nIf you would like to prevent gatsby-source-wordpress from fetching File nodes for each MediaItem node, set the type.MediaItem.createFileNodes option to false instead.\n`
          )
        )
      }

      return userPluginOptions
    },
  },
  {
    name: `pluginOptions.type.MediaItem.limit is not allowed`,
    test: ({ userPluginOptions }): boolean =>
      !!userPluginOptions?.type?.MediaItem?.limit,
    processor: ({ helpers, userPluginOptions }): void => {
      helpers.reporter.panic(
        formatLogMessage(
          `PluginOptions.type.MediaItem.limit is an disallowed plugin option.\nPlease remove the MediaItem.limit option from gatsby-config.js (currently set to ${userPluginOptions?.type?.MediaItem?.limit})\n\nMediaItem nodes are automatically limited to 0 and then fetched only when referenced by other node types. For example as a featured image, in custom fields, or in post_content.`
        )

View on GitHub (pinned to e85d62f177)

Solutions

1. Replace type.MediaItem.lazyNodes with type.MediaItem.createFileNodes: false in plugin options.
2. Remove lazyNodes entirely before upgrading to Gatsby v4+, where it panics.
3. Re-run the build to confirm MediaItems no longer create File nodes (if that was the goal).

When it happens

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

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/b51829911cf32d13. Report an issue: GitHub.