{"record":{"id":"7f5a973e152bc68f","repo":"gatsbyjs/gatsby","slug":"11903","errorCode":"11903","errorMessage":"There was an unhandled error during compilation for ${siteRoot}. Please run the command with the --verbose flag again.\\n${sourceMessage}","messagePattern":"There was an unhandled error during compilation for (.+?)\\. Please run the command with the --verbose flag again\\.\\\\n(.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby/src/utils/parcel/compile-gatsby-files.ts","lineNumber":239,"sourceCode":"        }\n\n        await compileGatsbyFiles(siteRoot, retry + 1)\n        return\n      }\n\n      const mainEntry = bundle.mainEntryPath\n      // mainEntry won't exist for shared chunks\n      if (mainEntry) {\n        if (mainEntry.endsWith(`.ts`)) {\n          compiledTSFilesCount = compiledTSFilesCount + 1\n        }\n      }\n    }\n  } catch (error) {\n    if (error.diagnostics) {\n      handleErrors(error.diagnostics)\n    } else {\n      reporter.panic({\n        id: `11903`,\n        error,\n        context: {\n          siteRoot,\n          sourceMessage: error.message,\n        },\n      })\n    }\n  }\n}\n\nfunction handleErrors(diagnostics: Array<Diagnostic>): void {\n  diagnostics.forEach(err => {\n    if (err.codeFrames) {\n      err.codeFrames.forEach(c => {\n        // Assuming that codeHighlights only ever has one entry in the array. Local tests only ever showed one\n        const codeHighlightsMessage = c?.codeHighlights[0]?.message\n        // If both messages are the same don't print the specific, otherwise they would be duplicate","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/utils/parcel/compile-gatsby-files.ts#L221-L257","documentation":"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.","triggerScenarios":"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.","commonSituations":"Gatsby/Parcel version mismatch after a partial upgrade; native module load failure; corrupted node_modules; unexpected Parcel API change; transient OS errors during bundling.","solutions":["Re-run with `gatsby develop --verbose` (or `gatsby build --verbose`) to surface the full error stack.","`gatsby clean`, then `rm -rf node_modules && npm install` (or yarn/pnpm equivalent) to rule out a corrupt install.","Align Gatsby CLI and `gatsby` package versions (`gatsby --version` vs package.json).","Read the `sourceMessage` in the panic and address the underlying cause (fs error, native module, etc.).","Open a reproduction at https://gatsby.dev/new-issue if no cause is identifiable."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isParcelDiagnosticArray(error) {\n  return error != null && Array.isArray(error.diagnostics)\n}","tryCatchPattern":"// Mirror Gatsby's own branch: route diagnostics to user-friendly handling,\n// surface everything else with full verbosity.\ntry {\n  await compileGatsbyFiles(siteRoot)\n} catch (error) {\n  if (isParcelDiagnosticArray(error)) {\n    handleErrors(error.diagnostics)\n  } else {\n    console.error('[compile] unexpected:', error)\n    process.exit(1)\n  }\n}","preventionTips":["Always have `--verbose` available in your build scripts to surface the sourceMessage.","Pin Gatsby CLI and gatsby package to the same version to avoid Parcel API drift.","Reinstall node_modules after switching Node major versions."],"tags":["parcel","compilation","unknown-error","diagnostics","verbose"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}