parcel-bundler/parcel · error · Error

Lazy includes can only be provided when lazy building is ena

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.

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)

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 excludes can only be provided when lazy building is ena
• Lazy bundling does not work with content hashing
• Library targets are not supported in serve mode.
• Expected package.json file in ${rootDir}
• Unexpected output file type ${ext} in target "${targetName}"

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