What causes "${err}" in gatsbyjs/gatsby?

Inspect the full error object in the terminal — the `${err}` message is often the only clue; look at the stack trace lines above the panic.

gatsbyjs/gatsby · critical

${err}

Error message

${err}

What it means

The non-Webpack branch of the html.js build catch in start-server. While building the develop-HTML bundle (`Stage.DevelopHTML`) any thrown error whose `name` is not `WebpackError` is re-thrown verbatim via `report.panic(err)`. Because the value is the raw error object, the rendered message is just `${err}`. Webpack-emitted errors fall through to the friendlier 309 message instead.

Source

Thrown at packages/gatsby/src/utils/start-server.ts:110

  const createIndexHtml = async (activity: ActivityTracker): Promise<void> => {
    try {
      const { rendererPath, close } = await buildRenderer(
        program,
        Stage.DevelopHTML,
        activity.span
      )
      await doBuildPages(
        rendererPath,
        [`/`],
        activity,
        workerPool,
        Stage.DevelopHTML
      )
      // close the compiler
      await close()
    } catch (err) {
      if (err.name !== `WebpackError`) {
        report.panic(err)
        return
      }
      report.panic(
        report.stripIndent`
          There was an error compiling the html.js component for the development server.
          See our docs page on debugging HTML builds for help https://gatsby.dev/debug-html
        `,
        err
      )
    }
  }
  const indexHTMLActivity = report.phantomActivity(`building index.html`, {})

  let pageRenderer: string
  if (process.env.GATSBY_EXPERIMENTAL_DEV_SSR) {
    const { buildRenderer } = require(`../commands/build-html`)
    pageRenderer = (await buildRenderer(program, Stage.DevelopHTML))
      .rendererPath

View on GitHub (pinned to 8b06340921)

Solutions

Inspect the full error object in the terminal — the `${err}` message is often the only clue; look at the stack trace lines above the panic.
Temporarily disable custom `gatsby-ssr.js`/`gatsby-browser.js` and plugins to isolate which one throws.
Run `gatsby clean` and retry.
If the error originates from a plugin, update or pin the plugin to a version compatible with your Gatsby major.
See https://gatsby.dev/debug-html for the structured debug flow.

Defensive patterns

Strategy: try-catch

Type guard

function isWebpackError(err) {
  return err != null && err.name === 'WebpackError'
}

Try / catch

// Mirror Gatsby's branch so non-webpack failures surface their real shape.
try {
  await doBuildPages(rendererPath, ['/'], activity, workerPool, Stage.DevelopHTML)
} catch (err) {
  if (isWebpackError(err)) {
    console.error('HTML.js compile error (see https://gatsby.dev/debug-html):', err)
  } else {
    console.error('Unexpected develop-HTML failure:', err)
  }
  throw err
}

Prevention

Isolate SSR code: keep gatsby-ssr.js minimal and tested separately.
Pin plugins to versions compatible with your Gatsby major.
Read the raw stack above the panic line; the generic message hides the cause.

When it happens

Trigger: `doBuildPages`/`close()` for the develop-HTML stage throws something that is not a WebpackError — e.g. a plugin `onCreatePage`/SSR error, a Node fs error reading html template, a native crash, or a thrown string/object without a `.name` of `WebpackError`.

Common situations: A custom HTML/SSR API (gatsby-ssr.js) throwing during develop-HTML render; a corrupt public/.cache; missing html.js source after an upgrade; plugin incompatibility during SSR.

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/0759e73d3cdbbaf6. Report an issue: GitHub.