11901

11901

Error message

Failed to compile Gatsby files ${origin ? `(${origin})` : ``}:\n    ${generalMessage}. ${specificMessage ?? ``}\n    ${hints}\n    ${filePath ? `File path: ${filePath}` : ``}

What it means

Thrown by `handleErrors` for each Parcel diagnostic that includes `codeFrames`. Gatsby formats the diagnostic into a panic containing the file path (from the first code frame), the general message, an optional specific message (only when it differs from the general one to avoid duplication), the diagnostic origin, and hints. This is the user-facing surface for compile errors in gatsby-node/gatsby-config that carry source location info.

Source

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

          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
        const specificMessage =
          codeHighlightsMessage === err.message
            ? undefined
            : codeHighlightsMessage
        reporter.panic({
          id: `11901`,
          context: {
            filePath: c?.filePath,
            generalMessage: err.message,
            specificMessage,
            origin: err?.origin,
            hints: err?.hints,
          },
        })
      })
    } else {
      reporter.panic({
        id: `11901`,
        context: {
          generalMessage: err.message,
          origin: err?.origin,
          hints: err?.hints,
        },

View on GitHub (pinned to 8b06340921)

Solutions

Open the `File path` from the message and fix the reported error at the indicated location.
Address the `hints` Parcel provides (often 'Cannot find module X' → install it, or a typo fix).
If it is a TS error, run `tsc --noEmit` on the file to get the full list.
Re-run with `--verbose` for additional context if the frame is insufficient.

Example fix

// before (gatsby-node.ts)
import { createPages } from "gatby" // typo
// after
import { createPages } from "gatsby"

Defensive patterns

Strategy: try-catch

Validate before calling

// Type-check gatsby-node / gatsby-config before invoking Gatsby compile.
// package.json script: "prebuild": "tsc --noEmit -p ."

Type guard

function isParcelDiagnosticWithFrame(err) {
  return err != null && Array.isArray(err.codeFrames) && err.codeFrames.length > 0
}

Prevention

Type-check gatsby-node.ts and gatsby-config.ts in CI (tsc --noEmit).
Install imported packages before referencing them in gatsby-node.
Keep an eye on the `origin`/`hints` fields; they name the failing rule.
Use a starter that already compiles, then edit incrementally.

When it happens

Trigger: Parcel emits a `Diagnostic` with a populated `codeFrames` array while compiling `gatsby-node.{ts,js}` or `gatsby-config.{ts,js}`. Concretely: a TypeScript syntax/type error, an invalid import, an export-const/getConfig signature mistake, or any source-level Parcel error with a code frame.

Common situations: Writing a new gatsby-node.ts with a typo or bad import; using an API that does not exist in the installed Gatsby version; TS strict-mode errors in config; referencing a module not installed; plugin gatsby-node files with syntax errors.

Related errors

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