What causes "config update contains changes to more than one group" in hyperledger/fabric?

Strip all groups other than the Orderer group from the update write set

config update contains changes to more than one group

Error message

config update contains changes to more than one group

What it means

Returned when the config update's WriteSet contains changes to more than one group. ensureConsensusTypeChangeOnly enforces that during consensus-type migration the update touches exactly one group — the Orderer group — and nothing else.

Source

Thrown at orderer/common/msgprocessor/maintenancefilter.go:188

	if err != nil {
		return errors.Wrap(err, "envelope to config update unmarshalling error")
	}

	configUpdate, err := configtx.UnmarshalConfigUpdate(configUpdateEnv.ConfigUpdate)
	if err != nil {
		return errors.Wrap(err, "config update unmarshalling error")
	}

	if len(configUpdate.WriteSet.Groups) == 0 {
		return errors.New("config update contains no changes")
	}

	if len(configUpdate.WriteSet.Values) > 0 {
		return errors.Errorf("config update contains changes to values in group %s", channelconfig.ChannelGroupKey)
	}

	if len(configUpdate.WriteSet.Groups) > 1 {
		return errors.New("config update contains changes to more than one group")
	}

	if ordGroup, ok1 := configUpdate.WriteSet.Groups[channelconfig.OrdererGroupKey]; ok1 {
		if len(ordGroup.Groups) > 0 {
			return errors.Errorf("config update contains changes to groups within the %s group",
				channelconfig.OrdererGroupKey)
		}

		if _, ok2 := ordGroup.Values[channelconfig.ConsensusTypeKey]; !ok2 {
			return errors.Errorf("config update does not contain the %s value", channelconfig.ConsensusTypeKey)
		}

		if len(ordGroup.Values) > 1 {
			return errors.Errorf("config update contain more then just the %s value in the %s group",
				channelconfig.ConsensusTypeKey, channelconfig.OrdererGroupKey)
		}
	} else {
		return errors.Errorf("update does not contain the %s group", channelconfig.OrdererGroupKey)

View on GitHub (pinned to 2736b63f8f)

Solutions

Strip all groups other than the Orderer group from the update write set
Perform application-group changes in a separate config update outside the maintenance window
Recompute the delta with configtxlator using a desired config that differs from current only in the Orderer ConsensusType

Example fix

// before: two groups in one update
WriteSet.Groups: { "Application": {...}, "Orderer": {...} }
// after: only orderer group
WriteSet.Groups: { "Orderer": { "Values": { "ConsensusType": {...} } } }

Defensive patterns

Strategy: validation

Validate before calling

if len(update.WriteSet.Groups) > 1 {
    return errors.New("update must touch only the Orderer group during consensus migration")
}

Prevention

Never batch application/org changes with the consensus migration update
Generate the desired config so it differs from current only in Orderer.ConsensusType
Check the delta's Groups keys before collecting signatures

When it happens

Trigger: A maintenance-mode config update whose WriteSet.Groups has two or more entries, e.g. changing both the Application group (e.g. adding an org) and the Orderer group in the same update, or changes to Orderer plus Channel group values.

Common situations: Batching routine channel administration (org adds, ACL changes in Application group) together with the consensus migration update to save a signing round-trip.

Related errors

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/a2a499342d6bbe2b. Report an issue: GitHub.