gatsbyjs/gatsby · error · EngineValidationError

Generated engines use disallowed import "${request}". Only a

Error message

Generated engines use disallowed import "${request}". Only allowed imports are to Node.js builtin modules or engines internals.

What it means

Thrown by the engine-validation child process which monkey-patches Node's `module._load`. It allows only Node builtins and imports resolving under `.cache/query-engine` or `.cache/page-ssr`; anything else (a user-code import or a node_modules dependency) that is not caught by a runtime fallback is treated as an engine-integrity violation. The validation exists to keep the generated query/page-ssr engines hermetic and side-effect free.

Source

Thrown at packages/gatsby/src/utils/validate-engines/child.ts:60

    const allowedPrefixes = [
      path.join(`.cache`, `query-engine`),
      path.join(`.cache`, `page-ssr`),
    ]
    const localRequire = mod.createRequire(parent.filename)
    const absPath = localRequire.resolve(request)
    const relativeToRoot = path.relative(directory, absPath)
    for (const allowedPrefix of allowedPrefixes) {
      if (relativeToRoot.startsWith(allowedPrefix)) {
        return originalModuleLoad(request, parent, isMain)
      }
    }

    // We throw on anything that is not allowed
    // Runtime might have try/catch for it and continue to work
    // (for example`msgpackr` have fallback if native `msgpack-extract` can't be loaded)
    // and we don't fail validation in those cases because error we throw will be handled.
    // We do want to fail validation if there is no fallback
    throw new EngineValidationError({ request, relativeToRoot, parent })
  }

  // workaround for gatsby-worker issue:
  // gatsby-worker gets bundled in engines and it will auto-init "child" module
  // if GATSBY_WORKER_MODULE_PATH env var is set. To prevent this we just unset
  // env var so it's falsy.
  process.env.GATSBY_WORKER_MODULE_PATH = ``

  // import engines, initiate them, if there is any error thrown it will be handled in parent process
  const { GraphQLEngine } = require(path.join(
    directory,
    `.cache`,
    `query-engine`
  ))
  require(path.join(directory, `.cache`, `page-ssr`))
  const graphqlEngine = new GraphQLEngine({
    dbPath: path.join(directory, `.cache`, `data`, `datastore`),
  })

View on GitHub (pinned to 8b06340921)

Solutions

Inspect the reported `request` and `relativeToRoot` in the error to see which module breached the engine boundary.
If the offender is a native optional dependency, ensure the package keeps its try/catch fallback so validation treats the failure as recoverable.
Move the offending import out of engine-executed code (it should run in the main build process, not in the engine).
Update Gatsby and all engine-related plugins to compatible versions; clear `.cache` and rebuild.

Example fix

// before: engine module imports user code
const data = require('../../../src/config')

// after: pass the value in via engine options / build-time inlining
const data = process.env.GATSBY_ENGINE_CONFIG

Defensive patterns

Strategy: validation

Validate before calling

// In plugin/engine code, gate imports so validation never sees a breach
const isAllowedImport = (request: string): boolean =>
  mod.builtinModules.includes(request) ||
  /^\.cache\/(query-engine|page-ssr)/.test(request)
if (!isAllowedImport(request)) { /* use inlined value instead */ }

Try / catch

// Wrap optional native loads so validation tolerates their failure
try { require('native-optional') } catch { /* fallback path */ }

Prevention

Keep engine-executed code hermetic: no imports of app code or runtime deps.
Preserve try/catch fallbacks around optional native dependencies.
Keep Gatsby and engine-related plugins on compatible versions.

When it happens

Trigger: During `gatsby build`, the engines bundle imports a module that resolves outside the allowed prefixes and there is no try/catch fallback around the import. Examples: an engine file reaches into `src/...` or into a node_modules package that was not bundled into the engine, or a transitive dependency attempts a native addon load (`msgpack-extract`, native bindings) without a fallback path.

Common situations: A plugin or theme injects code into the query/page-ssr engine that imports application code or a runtime dependency; a native addon is present in the dependency tree and its optional-load fallback was removed; Gatsby version mismatch where the engine bundling contract changed.

Related errors

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