parcel-bundler/parcel · error · ThrowableDiagnostic

Scope hoisting cannot be disabled for library targets.

Error message

Scope hoisting cannot be disabled for library targets.

What it means

Library targets must be scope-hoisted because their output is consumed by other tooling and must be a single flattened module graph. This guard (in the COMMON_TARGETS descriptor path) throws when `descriptor.scopeHoist === false` is set explicitly on a library target. The diagnostic highlights /targets/<name>/scopeHoist in package.json.

Source

Thrown at packages/core/core/src/requests/TargetRequest.js:866

                  ]),
                },
              ],
              hints: [
                `Either change the output file extension to .mjs, add "type": "module" to package.json, or remove the declared outputFormat.`,
              ],
              documentationURL:
                'https://parceljs.org/features/targets/#library-targets',
            },
          });
        }

        if (descriptor.scopeHoist === false) {
          let contents: string =
            typeof pkgContents === 'string'
              ? pkgContents
              : // $FlowFixMe
                JSON.stringify(pkgContents, null, '\t');
          throw new ThrowableDiagnostic({
            diagnostic: {
              message: 'Scope hoisting cannot be disabled for library targets.',
              origin: '@parcel/core',
              codeFrames: [
                {
                  language: 'json',
                  filePath: pkgFilePath ?? undefined,
                  code: contents,
                  codeHighlights: generateJSONCodeHighlights(contents, [
                    {
                      key: `/targets/${targetName}/scopeHoist`,
                      type: 'value',
                    },
                  ]),
                },
              ],
              hints: [
                `The "${targetName}" target is meant for libraries. Either remove the "scopeHoist" option, or use a different target name.`,

View on GitHub (pinned to 59484858a1)

Solutions

1. Remove `"scopeHoist": false` from the library target.
2. Set `"scopeHoist": true` (or omit it) for the library target.
3. If you genuinely need non-hoisted output, build as an application target instead of a library.

Example fix

// before (package.json)
"targets": {
  "main": { "isLibrary": true, "scopeHoist": false }
}

// after
"targets": {
  "main": { "isLibrary": true }
}

function assertLibraryScopeHoist(targets) {
  for (const [name, d] of Object.entries(targets || {})) {
    if (d.isLibrary && d.scopeHoist === false) {
      throw new Error(`Target ${name} is a library and cannot disable scope hoisting.`);
    }
  }
}

function isLibraryScopeHoistValid(d) {
  return !(d?.isLibrary === true && d?.scopeHoist === false);
}

try { await parcel.run(); } catch (e) {
  if (/Scope hoisting cannot be disabled for library targets/.test(e.message)) {
    console.error('Remove scopeHoist:false from library targets.');
  } else throw e;
}

When it happens

Trigger: Setting `"scopeHoist": false` under a common library target (main/module/types) in package.json.

Common situations: Disabling scope hoisting globally to debug a tree-shaking issue and forgetting to re-enable for library builds; copying app-only options into a library target; trying to reduce build time by skipping scope hoisting on a published package.

Related errors

• Library targets are not supported in serve mode.
• Unexpected output file type ${ext} in target "${targetName}"
• The "global" output format is not supported in the "${target
• Invalid distPath for target "${targetName}"
• Declared output format "${descriptor.outputFormat}" does not

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