{"record":{"id":"3998549bfc5f08cf","repo":"parcel-bundler/parcel","slug":"lazy-bundling-does-not-work-with-content-hashing","errorCode":null,"errorMessage":"Lazy bundling does not work with content hashing","messagePattern":"Lazy bundling does not work with content hashing","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/core/src/resolveOptions.js","lineNumber":145,"sourceCode":"\n  let shouldBuildLazily = initialOptions.shouldBuildLazily ?? false;\n  let lazyIncludes = compileGlobs(initialOptions.lazyIncludes ?? []);\n  if (lazyIncludes.length > 0 && !shouldBuildLazily) {\n    throw new Error(\n      'Lazy includes can only be provided when lazy building is enabled',\n    );\n  }\n  let lazyExcludes = compileGlobs(initialOptions.lazyExcludes ?? []);\n  if (lazyExcludes.length > 0 && !shouldBuildLazily) {\n    throw new Error(\n      'Lazy excludes can only be provided when lazy building is enabled',\n    );\n  }\n\n  let shouldContentHash =\n    initialOptions.shouldContentHash ?? initialOptions.mode === 'production';\n  if (shouldBuildLazily && shouldContentHash) {\n    throw new Error('Lazy bundling does not work with content hashing');\n  }\n\n  let env = {\n    ...(await loadDotEnv(\n      initialOptions.env ?? {},\n      inputFS,\n      path.join(projectRoot, 'index'),\n      projectRoot,\n    )),\n    ...process.env,\n    ...initialOptions.env,\n  };\n\n  let port = determinePort(initialOptions.serveOptions, env.PORT);\n\n  return {\n    config: getRelativeConfigSpecifier(\n      inputFS,","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/parcel-bundler/parcel/blob/59484858a1a0bcbb71f74088956bb437a2db6505/packages/core/core/src/resolveOptions.js#L127-L163","documentation":"Lazy bundling and content hashing are mutually exclusive. Content hashing renames output files based on content; lazy bundling defers compilation and assumes stable bundle references, so combining them would invalidate lazy references whenever content changes. resolveOptions throws when both shouldBuildLazily and shouldContentHash are true. Note shouldContentHash defaults to true in production mode.","triggerScenarios":"Setting `shouldBuildLazily: true` while content hashing is enabled — explicitly via `shouldContentHash: true` OR implicitly because `mode === 'production'` (the default for shouldContentHash).","commonSituations":"Enabling lazy builds in production (which auto-enables content hashing); setting both flags explicitly; programmatic option construction that flips mode to production without disabling hashing.","solutions":["Disable content hashing when using lazy builds: set `shouldContentHash: false`.","Disable lazy building if you need content-hashed output filenames.","In production with lazy builds, explicitly pass `shouldContentHash: false` because the production default would otherwise enable it."],"exampleFix":"// before\nconst parcel = new Parcel({\n  mode: 'production',\n  shouldBuildLazily: true\n});\n\n// after\nconst parcel = new Parcel({\n  mode: 'production',\n  shouldBuildLazily: true,\n  shouldContentHash: false\n});","handlingStrategy":"validation","validationCode":"function resolveLazyHashCoherence(opts) {\n  const lazy = opts.shouldBuildLazily === true;\n  const hash = opts.shouldContentHash ?? (opts.mode === 'production');\n  if (lazy && hash) {\n    throw new Error('Cannot combine lazy bundling with content hashing; disable one.');\n  }\n}","typeGuard":"function lazyAndHashCompatible(o) {\n  const lazy = o.shouldBuildLazily === true;\n  const hash = o.shouldContentHash ?? (o.mode === 'production');\n  return !(lazy && hash);\n}","tryCatchPattern":"try { new Parcel(opts); } catch (e) {\n  if (/Lazy bundling does not work with content hashing/.test(e.message)) {\n    opts.shouldContentHash = false;\n    new Parcel(opts);\n  } else throw e;\n}","preventionTips":["In production, explicitly set `shouldContentHash: false` when enabling lazy builds.","Remember `shouldContentHash` defaults to true in production mode.","Document the lazy↔hash incompatibility in shared option presets."],"tags":["parcel","lazy-build","content-hash","options","config"],"backgroundTag":null,"analyzedSha":"59484858a1a0bcbb71f74088956bb437a2db6505","analyzedAt":"2026-08-13T04:06:35.925Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}