parcel-bundler/parcel · error · Error

Only one spread element can be included in a config pipeline

Error message

Only one spread element can be included in a config pipeline

What it means

Thrown by mergePipelines() when the extending pipeline (ext) contains more than one '...' spread element. The spread element is used to insert the base pipeline's contents at a specific position; only one insertion point is allowed per pipeline to keep merge semantics unambiguous.

Source

Thrown at packages/core/core/src/requests/ParcelConfigRequest.js:660

function assertPurePipeline(
  pipeline: ExtendableParcelConfigPipeline,
): PureParcelConfigPipeline {
  return pipeline.map(s => {
    invariant(typeof s !== 'string');
    return s;
  });
}

export function mergePipelines(
  base: ?ExtendableParcelConfigPipeline,
  ext: ?ExtendableParcelConfigPipeline,
): ExtendableParcelConfigPipeline {
  if (ext == null) {
    return base ?? [];
  }

  if (ext.filter(v => v === '...').length > 1) {
    throw new Error(
      'Only one spread element can be included in a config pipeline',
    );
  }

  // Merge the base pipeline if a rest element is defined
  let spreadIndex = ext.indexOf('...');
  if (spreadIndex >= 0) {
    return [
      ...ext.slice(0, spreadIndex),
      ...(base ?? []),
      ...ext.slice(spreadIndex + 1),
    ];
  } else {
    return ext;
  }
}

export function mergeMaps<K: string, V>(

View on GitHub (pinned to 59484858a1)

Solutions

Keep only one '...' in each pipeline array — it represents the entire inherited base pipeline.
Place the single '...' where you want the base plugins to run: before your additions, after them, or in between.
If you need base plugins in two positions, explicitly list the base plugin names instead of using two spreads.

Example fix

// before — .parcelrc
{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.js": ["...", "my-plugin", "..."]
  }
}

// after — single spread
{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.js": ["my-plugin", "..."]
}

Defensive patterns

Strategy: validation

Validate before calling

function validatePipelineSpreadCount(pipeline) {
  if (!Array.isArray(pipeline)) return;
  const spreadCount = pipeline.filter(v => v === '...').length;
  if (spreadCount > 1) {
    throw new Error(`Pipeline has ${spreadCount} spread elements ('...'); only one is allowed.`);
  }
}

Prevention

Remember that '...' represents the entire inherited base pipeline — use it once.
If you need base plugins in multiple positions, list them by name explicitly.
Review the Parcel config merging documentation before writing complex pipelines.

When it happens

Trigger: mergePipelines(base, ext) is called during config chain processing when a child .parcelrc extends a parent. If the ext pipeline array filters to more than one element equal to '...', the error fires before any merging occurs.

Common situations: Writing a custom .parcelrc pipeline with multiple '...' entries thinking they each insert the base at different positions; copy-pasting pipeline fragments that each had their own spread; misunderstanding that '...' represents the entire base pipeline, not a per-position placeholder.

Related errors

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