{"record":{"id":"133be1a0069f887a","repo":"gatsbyjs/gatsby","slug":"loading-indicator-should-never-be-imported-in-code","errorCode":null,"errorMessage":"Loading indicator should never be imported in code that doesn't target only browsers","messagePattern":"Loading indicator should never be imported in code that doesn't target only browsers","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby/cache-dir/loading-indicator/indicator.js","lineNumber":8,"sourceCode":"import * as React from \"react\"\nimport { ShadowPortal } from \"../shadow-portal\"\nimport { Style } from \"./style\"\nimport { isLoadingIndicatorEnabled } from \"$virtual/loading-indicator\"\nimport { debugLog } from \"../debug-log\"\n\nif (typeof window === `undefined`) {\n  throw new Error(\n    `Loading indicator should never be imported in code that doesn't target only browsers`\n  )\n}\n\nif (module.hot) {\n  module.hot.accept(`$virtual/loading-indicator`, () => {\n    // isLoadingIndicatorEnabled is imported with ES import so no need\n    // for dedicated handling as HMR just replace it in that case\n  })\n}\n\n// HMR can rerun this, so check if it was set before\n// we also set it on window and not just in module scope because of HMR resetting\n// module scope\nif (typeof window.___gatsbyDidShowLoadingIndicatorBefore === `undefined`) {\n  window.___gatsbyDidShowLoadingIndicatorBefore = false\n}\n","sourceCodeStart":1,"sourceCodeEnd":26,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/cache-dir/loading-indicator/indicator.js#L1-L26","documentation":"Thrown at module evaluation time in loading-indicator/indicator.js when `typeof window === 'undefined'`. The loading indicator is a browser-only React component that uses DOM APIs; importing it in a Node/SSR context is a configuration error. Gatsby's build system is supposed to ensure this module only enters browser-targeted bundles.","triggerScenarios":"The indicator module is evaluated in a context where window is not defined — typically during SSR (gatsby-node.js, server rendering), or when a custom webpack/server config accidentally includes this browser-only module in a server bundle.","commonSituations":"Custom webpack configuration that bundles all of Gatsby's cache-dir into a server target, a Gatsby plugin that imports from the cache-dir directly, or a SSR framework (e.g. Gatsby Functions with SSR) that pulls in browser-only modules. Also seen when upgrading Gatsby versions where the loading indicator was newly introduced.","solutions":["Remove any custom imports from 'gatsby/cache-dir/loading-indicator' in your own code — these are internal browser-only modules.","Check custom webpack config for server targets that might include browser-only chunks; ensure proper target splitting.","If using SSR/Functions, ensure browser-only components are dynamically imported or guarded by `typeof window !== 'undefined'`.","Update Gatsby to the latest patch version — loading-indicator inclusion is handled by Gatsby's own webpack config."],"exampleFix":"// before — importing browser-only internal module in SSR code\nimport { LoadingIndicator } from 'gatsby/cache-dir/loading-indicator/indicator'\n\n// after — don't import internal cache-dir modules; use the public API\n// The loading indicator is auto-injected by Gatsby in dev mode, no import needed","handlingStrategy":"type-guard","validationCode":"// Guard browser-only imports in isomorphic code\nif (typeof window !== 'undefined') {\n  // safe to import or use browser-only modules here\n}","typeGuard":"// Type-level guard for browser-only modules (concept)\nfunction isBrowser(): boolean {\n  return typeof window !== 'undefined'\n}\n\n// Only import dynamically in browser context:\nif (isBrowser()) {\n  import('./browser-only-module').then(mod => mod.useIt())\n}","tryCatchPattern":null,"preventionTips":["Never import from gatsby/cache-dir/* in your application code — use the public Gatsby API.","Ensure webpack target splitting correctly separates browser and server bundles.","Use dynamic imports for browser-only modules in isomorphic code.","Review custom webpack config for server targets that might bundle browser modules."],"tags":["browser-only","ssr","webpack","internal-module","loading-indicator"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}