gatsbyjs/gatsby · critical

UNHANDLED EXCEPTION

Error message

UNHANDLED EXCEPTION

What it means

Top-level `process.on('uncaughtException', ...)` handler installed by the gatsby CLI. Any exception thrown in a synchronous scope (or an async scope without a catch) that reaches the event loop uncaught triggers this; the handler calls `report.panic` with the error and the process exits. The literal message is just a label; the attached error carries the real cause.

Source

Thrown at packages/gatsby-cli/src/index.ts:73

//     `)
//   )
// }

process.on(`unhandledRejection`, reason => {
  // This will exit the process in newer Node anyway so lets be consistent
  // across versions and crash

  // reason can be anything, it can be a message, an object, ANYTHING!
  // we convert it to an error object so we don't crash on structured error validation
  if (!(reason instanceof Error)) {
    reason = new Error(util.format(reason))
  }

  report.panic(`UNHANDLED REJECTION`, reason as Error)
})

process.on(`uncaughtException`, error => {
  report.panic(`UNHANDLED EXCEPTION`, error)
})

createCli(process.argv)

View on GitHub (pinned to 8b06340921)

Solutions

1. Inspect the attached error stack in the panic output to find the throwing file and line.
2. Add a try/catch around the throwing code or fix the null/undefined access.
3. Reproduce with `node --inspect` or `gatsby <cmd> --verbose` for a fuller stack.
4. Update/remove the plugin or user code identified as the source.

Example fix

// before: gatsby-config.js throws on missing env
module.exports = {
  siteMetadata: { key: process.env.API_KEY.toLowerCase() }  // API_KEY undefined
}

// after
const apiKey = process.env.API_KEY
if (!apiKey) throw new Error('API_KEY env var is required')
module.exports = { siteMetadata: { key: apiKey.toLowerCase() } }

// Wrap risky config/node code in try/catch to convert throws to structured errors
try { module.exports = require('./gatsby-config.safe') } catch (e) { console.error(e); process.exit(1) }

process.on('uncaughtException', (error) => {
  reporter.panic('UNHANDLED EXCEPTION', error)
})

When it happens

Trigger: Synchronous throw outside any try/catch (e.g. accessing a property of undefined in `gatsby-config`), or an error thrown in a callback/timer that nothing catches. The handler guarantees a structured panic and clean exit instead of a raw Node crash.

Common situations: Typo or null-deref in `gatsby-config.js`/`gatsby-node.js`; a plugin throwing synchronously in a lifecycle hook; a worker/timer callback raising an error; an incompatible plugin version throwing at load time.

Related errors

• UNHANDLED REJECTION
• Something went wrong when trying to add the plugins to the p
• starter ${starterPath} doesn't exist
• You can't create a starter from the existing directory. If y
• Please mention both starter package and project name along w

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