gatsbyjs/gatsby · error

Previous build used unsafe builtin method. We need to rebuil

Error message

Previous build used unsafe builtin method. We need to rebuild all pages

What it means

In calcDirtyHtmlFiles, when state.html.unsafeBuiltinWasUsedInSSR is true (a previous build's SSR run touched unsafe globals), Gatsby warns that it cannot trust the incremental HTML cache and must regenerate every page rather than only dirty ones. This is a cache-invalidation notice, not a thrown failure.

Source

Thrown at packages/gatsby/src/commands/build-utils.ts:153

        }
      }
    }

    if (!previousAction || overwritePreviousAction) {
      normalizedPagePathToAction.set(normalizedPagePath, {
        actualPath: path,
        action,
      })
      if (action === `delete`) {
        toDelete.add(path)
      } else if (action === `regenerate`) {
        toRegenerate.add(path)
      }
    }
  }

  if (state.html.unsafeBuiltinWasUsedInSSR) {
    reporter.warn(
      `Previous build used unsafe builtin method. We need to rebuild all pages`
    )
  }

  state.html.trackedHtmlFiles.forEach(function (htmlFile, path) {
    const page = state.pages.get(path)
    if (htmlFile.isDeleted || !page) {
      // FIXME: checking pages state here because pages are not persisted
      // and because of that `isDeleted` might not be set ...
      markActionForPage(path, `delete`)
    } else {
      if (getPageMode(page, state) === `SSG`) {
        if (htmlFile.dirty || state.html.unsafeBuiltinWasUsedInSSR) {
          markActionForPage(path, `regenerate`)
        } else {
          markActionForPage(path, `reuse`)
        }
      }

View on GitHub (pinned to e85d62f177)

Solutions

1. Eliminate the unsafe builtin usage reported in the prior build so the flag is never set
2. Accept the one-time full rebuild; subsequent builds will be incremental again
3. Audit SSR code paths (wrapPageElement, ssr rendering) for window/document access

When it happens

Trigger: Thrown at packages/gatsby/src/commands/build-utils.ts:153 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/2c7603dc79a6998e. Report an issue: GitHub.