{"record":{"id":"57fa9ffd9b76cecd","repo":"gatsbyjs/gatsby","slug":"there-was-an-error-compiling-the-html-js-component","errorCode":null,"errorMessage":"There was an error compiling the html.js component for the development server.\n          See our docs page on debugging HTML builds for help https://gatsby.dev/debug-html","messagePattern":"There was an error compiling the html\\.js component for the development server\\.\n          See our docs page on debugging HTML builds for help https://gatsby\\.dev/debug-html","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby/src/utils/start-server.ts","lineNumber":113,"sourceCode":"        program,\n        Stage.DevelopHTML,\n        activity.span\n      )\n      await doBuildPages(\n        rendererPath,\n        [`/`],\n        activity,\n        workerPool,\n        Stage.DevelopHTML\n      )\n      // close the compiler\n      await close()\n    } catch (err) {\n      if (err.name !== `WebpackError`) {\n        report.panic(err)\n        return\n      }\n      report.panic(\n        report.stripIndent`\n          There was an error compiling the html.js component for the development server.\n          See our docs page on debugging HTML builds for help https://gatsby.dev/debug-html\n        `,\n        err\n      )\n    }\n  }\n  const indexHTMLActivity = report.phantomActivity(`building index.html`, {})\n\n  let pageRenderer: string\n  if (process.env.GATSBY_EXPERIMENTAL_DEV_SSR) {\n    const { buildRenderer } = require(`../commands/build-html`)\n    pageRenderer = (await buildRenderer(program, Stage.DevelopHTML))\n      .rendererPath\n    const { initDevWorkerPool } = require(`./dev-ssr/render-dev-html`)\n    initDevWorkerPool()\n  } else {","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/utils/start-server.ts#L95-L131","documentation":"The WebpackError branch of the html.js build catch in start-server. When `doBuildPages(... Stage.DevelopHTML)` throws an error whose `name` is `WebpackError`, Gatsby wraps it in a friendly panic pointing at the html.js component and the debug-html docs. This means Webpack failed to compile the HTML bundle for the dev server.","triggerScenarios":"Webpack emits a `WebpackError` while compiling the develop-HTML bundle — module not found, syntax error in a component reached during SSR, import of a Node-only module in browser code, or a loader failure in the html build.","commonSituations":"An import error in gatsby-ssr.js or in a page/component rendered during SSR; importing a CSS/asset without the right loader; importing `fs`/other Node built-ins into client SSR code; a dependency that does not export an ESM/CJS shape Webpack expects.","solutions":["Follow https://gatsby.dev/debug-html and read the WebpackError detail above the panic line.","Fix the referenced module/import (install it, correct the path, or move it out of SSR).","Guard Node-only imports so they do not run during develop-HTML (use `typeof window !== 'undefined'` or dynamic imports).","`gatsby clean` after fixing to clear the stale html bundle.","Disable SSR (`GATSBY_EXPERIMENTAL_DEV_SSR` off) as a temporary workaround if the page works in pure client develop."],"exampleFix":"// before (gatsby-ssr.js)\nimport fs from \"fs\"\n// after — keep Node built-ins out of SSR\nconst fs = typeof require !== \"undefined\" ? require(\"fs\") : null","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isWebpackError(err) {\n  return err != null && err.name === 'WebpackError'\n}","tryCatchPattern":"// Catch WebpackError specifically to render the debug-html guidance.\ntry {\n  await doBuildPages(rendererPath, ['/'], activity, workerPool, Stage.DevelopHTML)\n} catch (err) {\n  if (isWebpackError(err)) {\n    console.error('There was an error compiling html.js. See https://gatsby.dev/debug-html')\n  }\n  throw err\n}","preventionTips":["Guard Node-only imports in SSR with typeof-window checks or dynamic imports.","Ensure all imports resolve (run the build locally before pushing to CI).","Keep loaders and asset imports consistent between browser and SSR builds.","Disable GATSBY_EXPERIMENTAL_DEV_SSR during SSR debugging to isolate client vs server paths."],"tags":["dev-server","html","ssr","webpack","develop","module-resolution"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}