{"record":{"id":"115b3b5935750012","repo":"gatsbyjs/gatsby","slug":"generated-engines-use-disallowed-import-request","errorCode":null,"errorMessage":"Generated engines use disallowed import \"${request}\". Only allowed imports are to Node.js builtin modules or engines internals.","messagePattern":"Generated engines use disallowed import \"(.+?)\"\\. Only allowed imports are to Node\\.js builtin modules or engines internals\\.","errorType":"validation","errorClass":"EngineValidationError","httpStatus":null,"severity":"error","filePath":"packages/gatsby/src/utils/validate-engines/child.ts","lineNumber":60,"sourceCode":"    const allowedPrefixes = [\n      path.join(`.cache`, `query-engine`),\n      path.join(`.cache`, `page-ssr`),\n    ]\n    const localRequire = mod.createRequire(parent.filename)\n    const absPath = localRequire.resolve(request)\n    const relativeToRoot = path.relative(directory, absPath)\n    for (const allowedPrefix of allowedPrefixes) {\n      if (relativeToRoot.startsWith(allowedPrefix)) {\n        return originalModuleLoad(request, parent, isMain)\n      }\n    }\n\n    // We throw on anything that is not allowed\n    // Runtime might have try/catch for it and continue to work\n    // (for example`msgpackr` have fallback if native `msgpack-extract` can't be loaded)\n    // and we don't fail validation in those cases because error we throw will be handled.\n    // We do want to fail validation if there is no fallback\n    throw new EngineValidationError({ request, relativeToRoot, parent })\n  }\n\n  // workaround for gatsby-worker issue:\n  // gatsby-worker gets bundled in engines and it will auto-init \"child\" module\n  // if GATSBY_WORKER_MODULE_PATH env var is set. To prevent this we just unset\n  // env var so it's falsy.\n  process.env.GATSBY_WORKER_MODULE_PATH = ``\n\n  // import engines, initiate them, if there is any error thrown it will be handled in parent process\n  const { GraphQLEngine } = require(path.join(\n    directory,\n    `.cache`,\n    `query-engine`\n  ))\n  require(path.join(directory, `.cache`, `page-ssr`))\n  const graphqlEngine = new GraphQLEngine({\n    dbPath: path.join(directory, `.cache`, `data`, `datastore`),\n  })","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/utils/validate-engines/child.ts#L42-L78","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: engine module imports user code\nconst data = require('../../../src/config')\n\n// after: pass the value in via engine options / build-time inlining\nconst data = process.env.GATSBY_ENGINE_CONFIG","handlingStrategy":"validation","validationCode":"// In plugin/engine code, gate imports so validation never sees a breach\nconst isAllowedImport = (request: string): boolean =>\n  mod.builtinModules.includes(request) ||\n  /^\\.cache\\/(query-engine|page-ssr)/.test(request)\nif (!isAllowedImport(request)) { /* use inlined value instead */ }","typeGuard":null,"tryCatchPattern":"// Wrap optional native loads so validation tolerates their failure\ntry { require('native-optional') } catch { /* fallback path */ }","preventionTips":["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."],"tags":["engines","validation","module-loading","build","hermetic"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}