parcel-bundler/parcel · error · Error

Lazy excludes can only be provided when lazy building is ena

Error message

Lazy excludes can only be provided when lazy building is enabled

What it means

Symmetric to error 51: `lazyExcludes` globs require lazy building to be enabled. resolveOptions compiles lazyExcludes and throws if any are present while shouldBuildLazily is falsy.

Source

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

    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(
      initialOptions.env ?? {},
      inputFS,
      path.join(projectRoot, 'index'),
      projectRoot,
    )),
    ...process.env,

View on GitHub (pinned to 59484858a1)

Solutions

1. Set `shouldBuildLazily: true` together with `lazyExcludes`.
2. Drop `lazyExcludes` if lazy building is not in use.
3. Drive both lazy flags from a single config variable.

Example fix

// before
const parcel = new Parcel({
  lazyExcludes: ['heavy-dep']
});

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

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

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

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

When it happens

Trigger: Passing `lazyExcludes` (glob patterns) without `shouldBuildLazily: true`.

Common situations: Adding excludes to tune lazy bundling without enabling the lazy feature; partial config migration; building options dynamically where excludes are set conditionally.

Related errors

• Lazy includes 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/5a53898c0c2b76f0. Report an issue: GitHub.