What causes "Unhandled rejection" in gatsbyjs/gatsby?

Look at the full error stack trace in the panic output -- it identifies which async operation rejected.

Unhandled rejection

Error message

Unhandled rejection

What it means

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).

Source

Thrown at packages/gatsby/src/services/initialize.ts:66

  !process.env.GATSBY_WORKER_POOL_WORKER
) {
  process.env.GATSBY_EXPERIMENTAL_DEV_SSR = `true`
  process.env.PRESERVE_FILE_DOWNLOAD_CACHE = `true`

  reporter.info(`
Two fast dev experiments are enabled: SSR in develop and preserving file download cache.

Please give feedback on their respective umbrella issues!

- https://gatsby.dev/dev-ssr-feedback
- https://gatsby.dev/cache-clearing-feedback
  `)
}

// Show stack trace on unhandled promises.
process.on(`unhandledRejection`, (reason: unknown) => {
  // https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33636
  reporter.panic((reason as Error) || `Unhandled rejection`)
})

// Override console.log to add the source file + line number.
// Useful for debugging if you lose a console.log somewhere.
// Otherwise leave commented out.
// require(`../bootstrap/log-line-function`)

type WebhookBody = IDataLayerContext["webhookBody"]

export async function initialize({
  program: args,
  parentSpan,
}: IBuildContext): Promise<{
  store: Store<IGatsbyState, AnyAction>
  workerPool: WorkerPool.GatsbyWorkerPool
  webhookBody?: WebhookBody
  adapterManager?: IAdapterManager
}> {

View on GitHub (pinned to 8b06340921)

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.

Example fix

// before
const data = await fetch(remoteUrl)

// after
let data
try {
  data = await fetch(remoteUrl)
} catch (err) {
  reporter.warn(`Failed to fetch: ${err.message}`)
  return
}

Defensive patterns

Strategy: try-catch

Try / catch

// Always catch async errors in gatsby-node.js and plugins
exports.sourceNodes = async ({ actions, reporter }) => {
  try {
    const data = await fetchData()
    // process data
  } catch (err) {
    reporter.error('Source plugin fetch failed:', err)
    // decide whether to continue or rethrow
  }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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