{"record":{"id":"ff86c6e58ba15e10","repo":"gatsbyjs/gatsby","slug":"unhandled-rejection-ff86c6","errorCode":null,"errorMessage":"Unhandled rejection","messagePattern":"Unhandled rejection","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby/src/services/initialize.ts","lineNumber":66,"sourceCode":"  !process.env.GATSBY_WORKER_POOL_WORKER\n) {\n  process.env.GATSBY_EXPERIMENTAL_DEV_SSR = `true`\n  process.env.PRESERVE_FILE_DOWNLOAD_CACHE = `true`\n\n  reporter.info(`\nTwo fast dev experiments are enabled: SSR in develop and preserving file download cache.\n\nPlease give feedback on their respective umbrella issues!\n\n- https://gatsby.dev/dev-ssr-feedback\n- https://gatsby.dev/cache-clearing-feedback\n  `)\n}\n\n// Show stack trace on unhandled promises.\nprocess.on(`unhandledRejection`, (reason: unknown) => {\n  // https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33636\n  reporter.panic((reason as Error) || `Unhandled rejection`)\n})\n\n// Override console.log to add the source file + line number.\n// Useful for debugging if you lose a console.log somewhere.\n// Otherwise leave commented out.\n// require(`../bootstrap/log-line-function`)\n\ntype WebhookBody = IDataLayerContext[\"webhookBody\"]\n\nexport async function initialize({\n  program: args,\n  parentSpan,\n}: IBuildContext): Promise<{\n  store: Store<IGatsbyState, AnyAction>\n  workerPool: WorkerPool.GatsbyWorkerPool\n  webhookBody?: WebhookBody\n  adapterManager?: IAdapterManager\n}> {","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/services/initialize.ts#L48-L84","documentation":"This is a top-level unhandledRejection handler registered during Gatsby's initialization phase. Any Promise rejection that is not caught by application code reaches this handler and is passed to reporter.panic, which terminates the process. The message is the rejection reason (an Error or a string 'Unhandled rejection' fallback).","triggerScenarios":"Any async operation in Gatsby, plugins, or user code (gatsby-node.js, gatsby-config.js) that rejects a Promise without a .catch() or try/await/catch -- e.g. a fetch call failing, a source plugin timing out, an unhandled .then() chain.","commonSituations":"A source plugin's async API call fails without error handling. A createNode call in gatsby-node.js throws inside an async function without try/catch. Node.js version mismatch causing a native module to reject. Network plugin failing to fetch remote data.","solutions":["Look at the full error stack trace in the panic output -- it identifies which async operation rejected.","Wrap async plugin/gatsby-node logic in try/catch or add .catch() to all Promise chains.","Update the failing plugin or fix the underlying network/filesystem issue causing the rejection.","Run with --verbose for more context on which operation failed."],"exampleFix":"// before\nconst data = await fetch(remoteUrl)\n\n// after\nlet data\ntry {\n  data = await fetch(remoteUrl)\n} catch (err) {\n  reporter.warn(`Failed to fetch: ${err.message}`)\n  return\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Always catch async errors in gatsby-node.js and plugins\nexports.sourceNodes = async ({ actions, reporter }) => {\n  try {\n    const data = await fetchData()\n    // process data\n  } catch (err) {\n    reporter.error('Source plugin fetch failed:', err)\n    // decide whether to continue or rethrow\n  }\n}","preventionTips":["Wrap all async operations in gatsby-node.js and plugins with try/catch.","Add .catch() to every Promise chain, especially fetch/API calls.","Use --verbose to get more context on unhandled rejections.","Test source plugins with network failure scenarios."],"tags":["async","promise","unhandled-rejection","process-exit"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}