What causes "Unhandled rejection" in gatsbyjs/gatsby?

Search the stack trace printed above the panic for the worker file/line that rejected without a value.

Unhandled rejection

Error message

Unhandled rejection

What it means

Default panic message when a worker process reports an unhandledRejection with a falsy reason. In `initReporterMessagingInWorker`, only inside a gatsby-worker context, the process installs an `unhandledRejection` handler that calls `reporter.panic(reason || 'Unhandled rejection')` and an `uncaughtException` handler that panics on the error. So this string surfaces only when a promise rejected with `undefined`/`null`/`''` inside a Gatsby worker.

Source

Thrown at packages/gatsby/src/utils/worker/reporter.ts:25

): void {
  if (typeof reporter._initReporterMessagingInMain === `function`) {
    reporter._initReporterMessagingInMain(workerPool.onMessage.bind(workerPool))
  }
}

const gatsbyWorkerMessenger = getMessenger()
export function initReporterMessagingInWorker(): void {
  if (
    isWorker &&
    gatsbyWorkerMessenger &&
    typeof reporter._initReporterMessagingInWorker === `function`
  ) {
    reporter._initReporterMessagingInWorker(
      gatsbyWorkerMessenger.sendMessage.bind(gatsbyWorkerMessenger)
    )

    process.on(`unhandledRejection`, (reason: unknown) => {
      reporter.panic((reason as Error) || `Unhandled rejection`)
    })

    process.on(`uncaughtException`, function (err) {
      reporter.panic(err)
    })
  }
}

View on GitHub (pinned to 8b06340921)

Solutions

Search the stack trace printed above the panic for the worker file/line that rejected without a value.
Ensure all rejections carry a real Error: `throw new Error('...')` / `reject(new Error('...'))`.
If the origin is a plugin, update it or open an issue with the trace.
Run with `--verbose` and `--inspect-brk` on the worker to capture the rejection site.

Example fix

// before
function load(x) {
  if (!x) return Promise.reject()
}
// after
function load(x) {
  if (!x) return Promise.reject(new Error(`load() requires a value, got ${x}`))
}

Defensive patterns

Strategy: try-catch

Type guard

function isNonEmptyError(reason) {
  return reason instanceof Error || (typeof reason === 'string' && reason.length > 0)
}

Try / catch

// Top-of-worker guard: never let a falsy rejection reach the generic handler.
process.on('unhandledRejection', reason => {
  const err = isNonEmptyError(reason) ? reason : new Error('Unhandled rejection with empty reason')
  reporter.panic(err)
})

Prevention

Always reject/throw real Error objects with descriptive messages.
Add a global `process.on('unhandledRejection', ...)` in worker entrypoints that upgrades falsy reasons to an Error with a stack.
Run workers with --inspect-brk and 'trace unhandled' to find the rejection site.
Audit plugins/user code for bare `reject()` calls.

When it happens

Trigger: Code running inside a Gatsby worker (page renderer, parcel compile worker, etc.) rejects a promise with no value: `Promise.reject()` or `throw undefined`, or an async function completes without a value where a rejection was expected. The worker's unhandledRejection handler converts the falsy reason into this generic message.

Common situations: A plugin or user code in gatsby-node that does `reject()` with no argument inside a worker; an await on a function that returns undefined and is misused; native/worker IPC delivering an empty rejection; third-party code that swallows the error value.

Related errors

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