Usage of "cache" instance in "onPreInit" API is not supporte

Error message

Usage of "cache" instance in "onPreInit" API is not supported as this API runs before cache initialization (called in ${plugin})

What it means

The cache instance handed to plugins during onPreInit is a stub because the real cache (LMDB) is not initialized until after onPreInit runs. Any cache.get() call inside onPreInit throws, naming the offending plugin.

Source

Thrown at packages/gatsby/src/utils/api-runner-node.js:303

        originalDone.apply(activity)
        runningActivities.delete(activity)
      }

      return activity
    },
  }
}

const getUninitializedCache = plugin => {
  const message =
    `Usage of "cache" instance in "onPreInit" API is not supported as ` +
    `this API runs before cache initialization` +
    (plugin && plugin !== `default-site-plugin` ? ` (called in ${plugin})` : ``)

  return {
    // GatsbyCache
    async get() {
      throw new Error(message)
    },
    async set() {
      throw new Error(message)
    },
    async del() {
      throw new Error(message)
    },
  }
}

const availableActionsCache = new Map()
let publicPath
const runAPI = async (plugin, api, args, activity) => {
  const gatsbyNode = await importGatsbyPlugin(plugin, `gatsby-node`)

  if (gatsbyNode[api]) {
    const parentSpan = args && args.parentSpan
    const spanOptions = parentSpan ? { childOf: parentSpan } : {}

View on GitHub (pinned to 8b06340921)

Solutions

Move cache reads to onPreBootstrap (or any later lifecycle hook).
Defer the work that needs the cache with a callback/queue flushed in onPreBootstrap.
Use a transient in-memory placeholder during onPreInit and reconcile against the cache later.

Example fix

// before: throws in onPreInit
exports.onPreInit = async ({ cache }) => {
  const v = await cache.get('key')
}
// after: move to onPreBootstrap
exports.onPreBootstrap = async ({ cache }) => {
  const v = await cache.get('key')
}

Defensive patterns

Strategy: validation

Validate before calling

// Guard cache reads in any onPreInit hook
exports.onPreInit = async ({ cache }) => {
  // cache is a stub here; do NOT call cache.get in onPreInit
  // schedule the read for onPreBootstrap instead
}

Type guard

function isRealCache(cache) {
  return typeof cache.get === 'function' && cache.get.toString().indexOf('throw') === -1
}

Prevention

Only touch cache in onPreBootstrap or later lifecycle hooks.
Queue cache work during onPreInit and flush it once the cache is real.
Lint your plugin for cache.* calls inside onPreInit.

When it happens

Trigger: A plugin's onPreInit hook calls cache.get(...) (reading a previously stored value).

Common situations: Plugin migrated cache reads from onPreBootstrap into onPreInit; misordered lifecycle usage; plugin assuming cache is available everywhere.

Related errors

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