What causes "Lazy bundling does not work with content hashing" in parcel-bundler/parcel?

Disable content hashing when using lazy builds: set `shouldContentHash: false`.

parcel-bundler/parcel · error · Error

Lazy bundling does not work with content hashing

Error message

Lazy bundling does not work with content hashing

What it means

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.

Source

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

  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,
    ...initialOptions.env,
  };

  let port = determinePort(initialOptions.serveOptions, env.PORT);

  return {
    config: getRelativeConfigSpecifier(
      inputFS,

View on GitHub (pinned to 59484858a1)

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.

Example fix

// before
const parcel = new Parcel({
  mode: 'production',
  shouldBuildLazily: true
});

// after
const parcel = new Parcel({
  mode: 'production',
  shouldBuildLazily: true,
  shouldContentHash: false
});

Defensive patterns

Strategy: validation

Validate before calling

function resolveLazyHashCoherence(opts) {
  const lazy = opts.shouldBuildLazily === true;
  const hash = opts.shouldContentHash ?? (opts.mode === 'production');
  if (lazy && hash) {
    throw new Error('Cannot combine lazy bundling with content hashing; disable one.');
  }
}

Type guard

function lazyAndHashCompatible(o) {
  const lazy = o.shouldBuildLazily === true;
  const hash = o.shouldContentHash ?? (o.mode === 'production');
  return !(lazy && hash);
}

Try / catch

try { new Parcel(opts); } catch (e) {
  if (/Lazy bundling does not work with content hashing/.test(e.message)) {
    opts.shouldContentHash = false;
    new Parcel(opts);
  } else throw e;
}

Prevention

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.

When it happens

Trigger: Setting `shouldBuildLazily: true` while content hashing is enabled — explicitly via `shouldContentHash: true` OR implicitly because `mode === 'production'` (the default for shouldContentHash).

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

Related errors

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