gatsbyjs/gatsby · error

Node mutation detected ${codeFrame ? `${codeFrame}\n\n` : `

Error message

Node mutation detected

${codeFrame ? `${codeFrame}\n\n` : ``}${error.stack.replace(/^Error:?\s*/, ``)}

What it means

In the proxy `set` trap used by GATSBY_DETECT_NODE_MUTATIONS, a mutation of a node field was observed. The warning includes a stack trace and code frame pointing at the mutation site. This is a diagnostic guard enabled only when GATSBY_DETECT_NODE_MUTATIONS is set; direct node mutations break Gatsby's change-tracking invariants.

Source

Thrown at packages/gatsby/src/utils/detect-node-mutations.ts:85

  onSet?: (target: any, key: string | symbol, value: any) => boolean | undefined
} = {}): ProxyHandler<any> {
  function set(target, key, value): boolean {
    if (onSet) {
      const result = onSet(target, key, value)
      if (result !== undefined) {
        return result
      }
    }

    const error = new Error(`Stack trace:`)
    Error.captureStackTrace(error, set)

    if (error.stack && !reported.has(error.stack)) {
      reported.add(error.stack)
      const codeFrame = getNonGatsbyCodeFrameFormatted({
        stack: error.stack,
      })
      reporter.warn(
        `Node mutation detected\n\n${
          codeFrame ? `${codeFrame}\n\n` : ``
        }${error.stack.replace(/^Error:?\s*/, ``)}`
      )
    }
    return true
  }

  function get(target, key): any {
    const value = target[key]

    if (onGet) {
      const result = onGet(key, value)
      if (result !== undefined) {
        return result
      }
    }

View on GitHub (pinned to e85d62f177)

Solutions

1. Find the mutation site from the printed stack/code frame and stop mutating nodes directly
2. Use createNode or createNodeField actions instead of assigning properties on existing nodes
3. Disable GATSBY_DETECT_NODE_MUTATIONS after diagnosis to restore build performance

When it happens

Trigger: Thrown at packages/gatsby/src/utils/detect-node-mutations.ts:85 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/e0ebb19570674db5. Report an issue: GitHub.