parcel-bundler/parcel · error · Error

Lazy includes can only be provided when lazy building is…

Error message

Lazy includes can only be provided when lazy building is enabled

What it means

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.

Solutions

1. Set `shouldBuildLazily: true` alongside `lazyIncludes`.
2. Remove `lazyIncludes` if you do not intend to use lazy building.
3. Centralize lazy-build flag derivation so includes/excludes always travel with the master flag.

Example fix

// before
const parcel = new Parcel({
  lazyIncludes: ['node-dep-*']
});

// after
const parcel = new Parcel({
  shouldBuildLazily: true,
  lazyIncludes: ['node-dep-*']
});

function assertLazyIncludesRequiresFlag(opts) {
  if ((!opts.shouldBuildLazily) && Array.isArray(opts.lazyIncludes) && opts.lazyIncludes.length > 0) {
    throw new Error('Pass shouldBuildLazily:true when setting lazyIncludes.');
  }
}

function lazyOptionsCoherent(o) {
  return o.shouldBuildLazily === true || (o.lazyIncludes?.length ?? 0) === 0;
}

try { new Parcel(opts); } catch (e) {
  if (/Lazy includes can only be provided/.test(e.message)) {
    opts.shouldBuildLazily = true;
    new Parcel(opts);
  } else throw e;
}

When it happens

Trigger: Passing `lazyIncludes` (an array of glob patterns) to Parcel options without also setting `shouldBuildLazily: true`.

Common situations: 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.

Related errors

• Lazy bundling does not work with content hashing
• Lazy excludes can only be provided when lazy building is…
• Declared output format
• Expected package.json file in
• External modules are not supported when building for browser

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/acd33ece6d1c67cb. Report an issue: GitHub.

Appendix: source

Thrown at packages/core/core/src/resolveOptions.js:131

    (outputFS instanceof NodeFS
      ? new LMDBCache(cacheDir)
      : new FSCache(outputFS, cacheDir));

  let mode = initialOptions.mode ?? 'development';
  let shouldOptimize =
    initialOptions?.defaultTargetOptions?.shouldOptimize ??
    mode === 'production';

  let publicUrl = initialOptions?.defaultTargetOptions?.publicUrl ?? '/';
  let distDir =
    initialOptions?.defaultTargetOptions?.distDir != null
      ? path.resolve(inputCwd, initialOptions?.defaultTargetOptions?.distDir)
      : undefined;

  let shouldBuildLazily = initialOptions.shouldBuildLazily ?? false;
  let lazyIncludes = compileGlobs(initialOptions.lazyIncludes ?? []);
  if (lazyIncludes.length > 0 && !shouldBuildLazily) {
    throw new Error(
      'Lazy includes can only be provided when lazy building is enabled',
    );
  }
  let lazyExcludes = compileGlobs(initialOptions.lazyExcludes ?? []);
  if (lazyExcludes.length > 0 && !shouldBuildLazily) {
    throw new Error(
      'Lazy excludes can only be provided when lazy building is enabled',
    );
  }

  let shouldContentHash =
    initialOptions.shouldContentHash ?? initialOptions.mode === 'production';
  if (shouldBuildLazily && shouldContentHash) {
    throw new Error('Lazy bundling does not work with content hashing');
  }

  let env = {
    ...(await loadDotEnv(

View on GitHub (pinned to 59484858a1)