{"record":{"id":"acd33ece6d1c67cb","repo":"parcel-bundler/parcel","slug":"lazy-includes-can-only-be-provided-when-lazy-build","errorCode":null,"errorMessage":"Lazy includes can only be provided when lazy building is enabled","messagePattern":"Lazy includes can only be provided when lazy building is enabled","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/core/src/resolveOptions.js","lineNumber":131,"sourceCode":"    (outputFS instanceof NodeFS\n      ? new LMDBCache(cacheDir)\n      : new FSCache(outputFS, cacheDir));\n\n  let mode = initialOptions.mode ?? 'development';\n  let shouldOptimize =\n    initialOptions?.defaultTargetOptions?.shouldOptimize ??\n    mode === 'production';\n\n  let publicUrl = initialOptions?.defaultTargetOptions?.publicUrl ?? '/';\n  let distDir =\n    initialOptions?.defaultTargetOptions?.distDir != null\n      ? path.resolve(inputCwd, initialOptions?.defaultTargetOptions?.distDir)\n      : undefined;\n\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(","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/parcel-bundler/parcel/blob/59484858a1a0bcbb71f74088956bb437a2db6505/packages/core/core/src/resolveOptions.js#L113-L149","documentation":"Lazy building (on-demand bundle compilation) must be enabled via `shouldBuildLazily` before any `lazyIncludes` globs take effect. resolveOptions compiles the lazyIncludes globs and, if any are present while shouldBuildLazily is falsy, throws immediately. This is a hard precondition guard at option resolution time.","triggerScenarios":"Passing `lazyIncludes` (an array of glob patterns) to Parcel options without also setting `shouldBuildLazily: true`.","commonSituations":"Enabling lazy includes for dev-server speedups but forgetting the master switch; programmatically constructing options where lazyIncludes is conditionally set but shouldBuildLazily is not; copy-paste from a lazy-build config into a normal build.","solutions":["Set `shouldBuildLazily: true` alongside `lazyIncludes`.","Remove `lazyIncludes` if you do not intend to use lazy building.","Centralize lazy-build flag derivation so includes/excludes always travel with the master flag."],"exampleFix":"// before\nconst parcel = new Parcel({\n  lazyIncludes: ['node-dep-*']\n});\n\n// after\nconst parcel = new Parcel({\n  shouldBuildLazily: true,\n  lazyIncludes: ['node-dep-*']\n});","handlingStrategy":"validation","validationCode":"function assertLazyIncludesRequiresFlag(opts) {\n  if ((!opts.shouldBuildLazily) && Array.isArray(opts.lazyIncludes) && opts.lazyIncludes.length > 0) {\n    throw new Error('Pass shouldBuildLazily:true when setting lazyIncludes.');\n  }\n}","typeGuard":"function lazyOptionsCoherent(o) {\n  return o.shouldBuildLazily === true || (o.lazyIncludes?.length ?? 0) === 0;\n}","tryCatchPattern":"try { new Parcel(opts); } catch (e) {\n  if (/Lazy includes can only be provided/.test(e.message)) {\n    opts.shouldBuildLazily = true;\n    new Parcel(opts);\n  } else throw e;\n}","preventionTips":["Always set `shouldBuildLazily: true` when configuring `lazyIncludes`/`lazyExcludes`.","Derive lazy flags from a single config switch.","Validate options before constructing Parcel."],"tags":["parcel","lazy-build","options","config"],"backgroundTag":null,"analyzedSha":"59484858a1a0bcbb71f74088956bb437a2db6505","analyzedAt":"2026-08-13T04:06:35.925Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}