Gatsby Build Error: ReferenceError - 'document' not defined during HTML Compilation

Question

Struggling with building my Gatsby site. When I run 'gatsby develop,' everything works fine. However, during the build process, I encounter errors like the one below. Has anyone faced this issue before and found a solution? Any help would be greatly appreciated!

ERROR Image

This is the error:

ERROR  UNKNOWN

Truncated page data information for the failed page "/": {
  "errors": {},
  "path": "/",
  "slicesMap": {},
  "pageContext": {}
}

failed Building static HTML for pages - 13.248s

 ERROR #95312  HTML.COMPILATION

"document" is not available during server-side rendering. Enable "DEV_SSR" to
  debug this during "gatsby develop".

See our docs page for more info on this error: https://gatsby.dev/debug-html

  WebpackError: ReferenceError: document is not defined

Already tried reinstalling npm packages and deleting node-modules along with package-lock.json, but still encountering the 'document' ReferenceError during Gatsby build. Any alternative or additional troubleshooting suggestions are welcome.

package.json

{
  "name": "Test Project",
  "author": "Akila Gunasekara",
  "version": "1.1.0",
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build",
    "start": "gatsby develop",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
  },
  "dependencies": {
    "@emotion/react": "^11.11.1",
    "@emotion/styled": "^11.11.0",
    "@gatsbyjs/reach-router": "^2.0.1",
    "@mui/icons-material": "^5.14.19",
    "@mui/material": "^5.14.20",
    "animate.css": "^4.1.1",
    "gatsby": "^5.12.12",
    "gatsby-link": "^5.12.1",
    "gatsby-plugin-emotion": "^7.25.0",
    "gatsby-plugin-image": "^3.12.3",
    "gatsby-plugin-manifest": "^5.13.1",
    "gatsby-plugin-postcss": "^6.12.0",
    "gatsby-plugin-react-helmet": "^6.12.0",
    "gatsby-plugin-sharp": "^5.12.3",
    "gatsby-react-router-scroll": "^6.12.0",
    "gatsby-script": "^2.12.0",
    "gatsby-source-filesystem": "^5.12.1",
    "gatsby-theme-codebushi": "^1.0.0",
    "gatsby-transformer-sharp": "^5.12.3",
    "postcss": "^8.3.8",
    "react": "^18.2.0",
    "react-anchor-link-smooth-scroll": "^1.0.12",
    "react-animation-on-scroll": "^5.1.0",
    "react-dom": "^18.2.0",
    "react-helmet": "^6.1.0",
    "react-hook-form": "^7.48.2",
    "react-router-dom": "^6.20.1"
  },
  "devDependencies": {
    "eslint": "^7.21.0",
    "eslint-config-airbnb": "^18.0.1",
    "eslint-config-prettier": "^8.1.0",
    "eslint-plugin-import": "^2.19.1",
    "eslint-plugin-jsx-a11y": "^6.2.3",
    "eslint-plugin-prettier": "^3.1.2",
    "eslint-plugin-react": "^7.17.0",
    "eslint-plugin-react-hooks": "^4.2.0",
    "prettier": "^2.2.1"
  }
}

gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: `gatsby-theme-codebushi`,
      options: {
        tailwindConfig: `tailwind.config.js`
      }
    },
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        icon: 'src/assets/icons/icon.png'
      }
    },
    'gatsby-plugin-image',
    'gatsby-plugin-sharp',
    'gatsby-transformer-sharp',
  ],
};

Answer 1

The error message indicates that the problem relates to the page being served at /, so this probably means that the issue lies in a file like src/pages/index.js or src/pages/index.tsx.

As you mention, everything works in a development server but not when you build the site. The error mentions that document is not defined. I suspect that the issue relates to the fact that the document in this case refers to the DOM, which is only available in a browser environment. However, when you actually build the site there is no browser (and hence no DOM!).

There are a couple of options for at least making this issue go away:

1. Conditional

You can wrap the code that references document in a conditional.

if (typeof window !== 'undefined') {
  // Code that references document goes here.
}

This is not ideal since this code will not actually be included in the build, but it should at least prevent the error.

2. Use a Hook in Client

If you have some code that needs specifically to run on the client you can use a useEffect hook.

useEffect(() => {
  // Code that references document goes here.
}, []);

If neither of these options helps then you should follow the suggestion in the error message and enable DEV_SSR.