gatsbyjs/gatsby · error

Unsafe builtin method was used, future builds will need to r

Error message

Unsafe builtin method was used, future builds will need to rebuild all pages

What it means

During HTML rendering (renderHTMLQueue), the SSR sandbox detected that page code used unsafe globals (e.g. window, document) during server-side rendering. Gatsby catches the error, records which page paths used which unsafe builtins, rethrows, and warns that all pages must be rebuilt next time because the incremental build cache for HTML is invalidated.

Source

Thrown at packages/gatsby/src/commands/build-html.ts:465

      if (activity && activity.tick) {
        activity.tick(pageSegment.length)
      }
    })
  } catch (e) {
    if (e?.context?.unsafeBuiltinsUsageByPagePath) {
      for (const [_pagePath, arrayOfUsages] of Object.entries(
        e.context.unsafeBuiltinsUsageByPagePath
      )) {
        // @ts-ignore TS doesn't know arrayOfUsages is Iterable
        for (const unsafeUsageStack of arrayOfUsages) {
          uniqueUnsafeBuiltinUsedStacks.add(unsafeUsageStack)
        }
      }
    }
    throw e
  } finally {
    if (uniqueUnsafeBuiltinUsedStacks.size > 0) {
      console.warn(
        `Unsafe builtin method was used, future builds will need to rebuild all pages`
      )
      store.dispatch({
        type: `SSR_USED_UNSAFE_BUILTIN`,
      })
    }

    for (const unsafeBuiltinUsedStack of uniqueUnsafeBuiltinUsedStacks) {
      const prettyError = createErrorFromString(
        unsafeBuiltinUsedStack,
        `${htmlComponentRendererPath}.map`
      )

      const warningMessage = `${prettyError.stack}${
        prettyError.codeFrame ? `\n\n${prettyError.codeFrame}\n` : ``
      }`

      reporter.warn(warningMessage)

View on GitHub (pinned to e85d62f177)

Solutions

1. Guard browser globals in components with typeof window !== `undefined` checks or the globalThis prefix
2. Move DOM-dependent code into useEffect or wrapSSR/replaceHydrateFunction-safe paths
3. Use Gatsby's SSR APIs or gatsby-plugin-less-unsafe-globals style fixes to avoid touching globals during SSR

When it happens

Trigger: Thrown at packages/gatsby/src/commands/build-html.ts:465 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/440f11080f968675. Report an issue: GitHub.