illegal consensus type detected during consensus metadata va

Error message

illegal consensus type detected during consensus metadata validation: %s

What it means

Raised when the consensus type found in the new orderer config during metadata validation is neither 'etcdraft' nor 'BFT'. The code first panics with the same message (unrecoverable programming/config state) and then returns this error defensively.

Source

Thrown at orderer/consensus/etcdraft/chain.go:1480

	}

	// metadata was not updated
	if newOrdererConfig.ConsensusMetadata() == nil {
		return nil
	}

	if newOrdererConfig.ConsensusType() != "etcdraft" {
		if newOrdererConfig.ConsensusType() == "BFT" {
			// This is a migration, so we have to validate the config change and make sure that endpoints per org are configured
			for _, org := range newOrdererConfig.Organizations() {
				if len(org.Endpoints()) == 0 {
					return errors.Errorf("illegal orderer config detected during consensus metadata validation: endpoints of org %s are missing", org.Name())
				}
			}
			return nil
		} else {
			c.logger.Panicf("illegal consensus type detected during consensus metadata validation: %s", newOrdererConfig.ConsensusType())
			return errors.Errorf("illegal consensus type detected during consensus metadata validation: %s", newOrdererConfig.ConsensusType())

		}
	}

	if oldOrdererConfig == nil {
		c.logger.Panic("Programming Error: ValidateConsensusMetadata called with nil old channel config")
		return nil
	}

	if oldOrdererConfig.ConsensusMetadata() == nil {
		c.logger.Panic("Programming Error: ValidateConsensusMetadata called with nil old metadata")
		return nil
	}

	oldMetadata := &etcdraft.ConfigMetadata{}
	if err := proto.Unmarshal(oldOrdererConfig.ConsensusMetadata(), oldMetadata); err != nil {
		c.logger.Panicf("Programming Error: Failed to unmarshal old etcdraft consensus metadata: %v", err)
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Correct the ConsensusType in the channel config to 'etcdraft' (or 'BFT' when migrating on a supporting version).
Regenerate the config update from a known-good configtx.yaml profile.
Ensure all orderers run a Fabric version that supports the intended consensus type.
Validate the decoded config with configtxlator before submitting the update.

Example fix

// channel config
# before
ConsensusType: "etcd raft"
# after
ConsensusType: "etcdraft"

Defensive patterns

Strategy: validation

Validate before calling

for _, org := range newCfg.Orderer.Organizations {
    if len(org.OrdererEndpoints) == 0 {
        return fmt.Errorf("org %s has no OrdererEndpoints; required for BFT migration", org.Name)
    }
}

Prevention

Define OrdererEndpoints for every org before migration.
Validate the new config with configtxlator decode.
Follow the official consensus-type migration checklist.
Test migration on a throwaway network first.

When it happens

Trigger: A config update carries an unsupported ConsensusType value in the Orderer group — a typo or a Fabric build without support for the configured consensus type.

Common situations: Hand-edited channel config introducing an invalid ConsensusType string; using a config generated for a different Fabric version with consensus plugins this build lacks; mixed-version cluster during migration.

Related errors

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