gatsbyjs/gatsby · critical

Missing compiler

Error message

Missing compiler

What it means

During develop-mode recompilation (hot reload of changes), Gatsby expects the webpackWatching instance (the webpack watcher) to be present on the build context. If it is undefined -- meaning the webpack dev server was never started or the context was not properly initialized -- the recompile cannot proceed.

Source

Thrown at packages/gatsby/src/services/recompile.ts:23

import reporter from "gatsby-cli/lib/reporter"
import { emitter } from "../redux"
import { buildRenderer } from "../commands/build-html"
import { Stage } from "../commands/types"
import { clearRequireCacheRecursively } from "../utils/clear-require-cache"

export async function recompile(context: IBuildContext): Promise<Stats> {
  const [stats] = await Promise.all([
    recompileDevBundle(context),
    recompileSSRBundle(context),
  ])
  return stats
}

async function recompileDevBundle({
  webpackWatching,
}: IBuildContext): Promise<Stats> {
  if (!webpackWatching) {
    reporter.panic(`Missing compiler`)
  }
  return new Promise<Stats>(resolve => {
    function finish(stats: Stats): void {
      emitter.off(`COMPILATION_DONE`, finish)
      resolve(stats)
    }
    emitter.on(`COMPILATION_DONE`, finish)
    webpackWatching.resume()
    // Suspending is just a flag, so it's safe to re-suspend right away
    webpackWatching.suspend()
  })
}

async function recompileSSRBundle({
  program,
  websocketManager,
  recompiledFiles = new Set(),
}: IBuildContext): Promise<void> {

View on GitHub (pinned to 8b06340921)

Solutions

1. Run `gatsby clean` and restart `gatsby develop` -- this is almost always a transient state corruption.
2. If it persists, update Gatsby to the latest patch version -- this path is an internal invariant that should not be reachable.
3. Report a bug with a minimal reproduction if it occurs on a clean cache with the latest version.

// Ensure webpackWatching is present before calling recompile
function hasWebpackWatching(ctx) {
  return ctx && ctx.webpackWatching != null && typeof ctx.webpackWatching.resume === 'function'
}

if (!hasWebpackWatching(context)) {
  throw new Error('Cannot recompile: webpack watcher not initialized. Restart gatsby develop.')
}

When it happens

Trigger: The recompileDevBundle function is called when webpackWatching on IBuildContext is falsy. This happens when the develop state machine enters the recompile step without having first run startWebpackServer, or if the watcher was lost due to a prior crash.

Common situations: State machine ordering bug where recompile runs before webpack server start. A prior webpack crash destroyed the watcher context. Custom integrations that call recompile directly without establishing the dev server. Internal regression in develop bootstrap flow.

Related errors

• Missing required params
• something changed in webpack but I don't know what
• Encountered unknown module type: ${module.type}. Please open
• ${event.data}
• page not found

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