parcel-bundler/parcel · error · Error

Feature flag ${name} must be set to true or false

Error message

Feature flag ${name} must be set to true or false

What it means

Thrown by the Parcel CLI's --feature-flag option parser when a boolean feature flag is given a value other than 'true' or 'false'. The parser splits the input on '=', looks up the flag name in DEFAULT_FEATURE_FLAGS, and if the flag's default type is boolean, strictly requires the value to be the string 'true' or 'false'. Non-boolean flags pass through the raw string value.

Source

Thrown at packages/core/parcel/src/cli.js:145

    parseOptionInt,
  ],
  '--reporter <name>': [
    'additional reporters to run',
    (val, acc) => {
      acc.push(val);
      return acc;
    },
    [],
  ],
  '--feature-flag <name=value>': [
    'sets the value of a feature flag',
    (value, previousValue) => {
      let [name, val] = value.split('=');
      if (name in DEFAULT_FEATURE_FLAGS) {
        let featureFlagValue;
        if (typeof DEFAULT_FEATURE_FLAGS[name] === 'boolean') {
          if (val !== 'true' && val !== 'false') {
            throw new Error(
              `Feature flag ${name} must be set to true or false`,
            );
          }
          featureFlagValue = val === 'true';
        }
        previousValue[name] = featureFlagValue ?? String(val);
      } else {
        INTERNAL_ORIGINAL_CONSOLE.warn(
          `Unknown feature flag ${name} specified, it will be ignored`,
        );
      }
      return previousValue;
    },
    {},
  ],
};

var hmrOptions = {

View on GitHub (pinned to 59484858a1)

Solutions

1. Use exactly 'true' or 'false' as the value: `--feature-flag FlagName=true`.
2. Check DEFAULT_FEATURE_FLAGS to confirm the flag exists and is boolean-typed.
3. If the flag name is unknown, the CLI warns 'Unknown feature flag' instead of throwing — so verify spelling.

Example fix

// before
$ parcel build --feature-flag cacheHeaders=1
// Error: Feature flag cacheHeaders must be set to true or false

// after
$ parcel build --feature-flag cacheHeaders=true

// Validate feature flag value before passing to CLI
const DEFAULT_FEATURE_FLAGS = require('@parcel/core').DEFAULT_FEATURE_FLAGS;

function buildFeatureFlagArg(name, value) {
  if (!(name in DEFAULT_FEATURE_FLAGS)) {
    console.warn(`Unknown feature flag: ${name}`);
    return null;
  }
  if (typeof DEFAULT_FEATURE_FLAGS[name] === 'boolean') {
    if (value !== 'true' && value !== 'false') {
      throw new Error(`Flag ${name} requires 'true' or 'false', got: ${value}`);
    }
  }
  return `--feature-flag ${name}=${value}`;
}

When it happens

Trigger: Running `parcel build --feature-flag SomeFlag=yes` or `parcel serve --feature-flag SomeFlag=1` or `parcel --feature-flag SomeFlag` (no value). The value.split('=') yields [name, undefined] or [name, 'yes'], and the boolean check fails for any value not exactly 'true' or 'false'.

Common situations: Using `1`/`0` instead of `true`/`false` (common in shell scripts). Using `yes`/`no` (common in other CLI tools). Omitting the `=value` entirely. Typo in the value (e.g., `ture` instead of `true`). Case sensitivity issues (`True` vs `true`).

Related errors

• Port ${portValue} is not a valid integer.
• Unknown environment feature: ${feature}
• Entry ${entry} does not exist
• Targets option is an empty array
• Could not find target with name "${target}"

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