gatsbyjs/gatsby · critical

11903

11903

Error message

There was an unhandled error during compilation for ${siteRoot}. Please run the command with the --verbose flag again.\n${sourceMessage}

What it means

Thrown by the top-level catch around the entire compile loop when an unexpected (non-diagnostic) error escapes. If the error has a `diagnostics` array it is forwarded to `handleErrors`; otherwise the error is wrapped in a panic with siteRoot and the raw `error.message`, advising `--verbose`. This is the catch-all for failures that are neither structured Parcel diagnostics nor the bundle-validation retry path.

Source

Thrown at packages/gatsby/src/utils/parcel/compile-gatsby-files.ts:239

        }

        await compileGatsbyFiles(siteRoot, retry + 1)
        return
      }

      const mainEntry = bundle.mainEntryPath
      // mainEntry won't exist for shared chunks
      if (mainEntry) {
        if (mainEntry.endsWith(`.ts`)) {
          compiledTSFilesCount = compiledTSFilesCount + 1
        }
      }
    }
  } catch (error) {
    if (error.diagnostics) {
      handleErrors(error.diagnostics)
    } else {
      reporter.panic({
        id: `11903`,
        error,
        context: {
          siteRoot,
          sourceMessage: error.message,
        },
      })
    }
  }
}

function handleErrors(diagnostics: Array<Diagnostic>): void {
  diagnostics.forEach(err => {
    if (err.codeFrames) {
      err.codeFrames.forEach(c => {
        // Assuming that codeHighlights only ever has one entry in the array. Local tests only ever showed one
        const codeHighlightsMessage = c?.codeHighlights[0]?.message
        // If both messages are the same don't print the specific, otherwise they would be duplicate

View on GitHub (pinned to 8b06340921)

Solutions

1. Re-run with `gatsby develop --verbose` (or `gatsby build --verbose`) to surface the full error stack.
2. `gatsby clean`, then `rm -rf node_modules && npm install` (or yarn/pnpm equivalent) to rule out a corrupt install.
3. Align Gatsby CLI and `gatsby` package versions (`gatsby --version` vs package.json).
4. Read the `sourceMessage` in the panic and address the underlying cause (fs error, native module, etc.).
5. Open a reproduction at https://gatsby.dev/new-issue if no cause is identifiable.

function isParcelDiagnosticArray(error) {
  return error != null && Array.isArray(error.diagnostics)
}

// Mirror Gatsby's own branch: route diagnostics to user-friendly handling,
// surface everything else with full verbosity.
try {
  await compileGatsbyFiles(siteRoot)
} catch (error) {
  if (isParcelDiagnosticArray(error)) {
    handleErrors(error.diagnostics)
  } else {
    console.error('[compile] unexpected:', error)
    process.exit(1)
  }
}

When it happens

Trigger: Any exception during the compile loop that does not expose a `diagnostics` property — e.g. a thrown string, a Node fs error, a TypeError inside Parcel plumbing, or a worker IPC failure. Reached when the error is not recognized as a compile diagnostic and not caught by the bundle-validation inner try/catch.

Common situations: Gatsby/Parcel version mismatch after a partial upgrade; native module load failure; corrupted node_modules; unexpected Parcel API change; transient OS errors during bundling.

Related errors

• 11901
• 11904
• 11701

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