hyperledger/fabric · error

invalid BFT consenter mapping configuration

Error message

invalid BFT consenter mapping configuration

What it means

Wraps an error from validateBFTConsenterMapping during a maintenance-mode migration to BFT. The consenter set in the next config's BFT metadata must correspond exactly to the ordering service endpoints/tls certs in the new orderer group configuration; a mismatch is rejected.

Source

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

		if !mf.permittedTargetConsensusTypes[nextOrdererConfig.ConsensusType()] {
			return errors.Errorf("attempted to change consensus type from %s to %s, transition not supported",
				ordererConfig.ConsensusType(), nextOrdererConfig.ConsensusType())
		}

		if nextOrdererConfig.ConsensusType() == "BFT" {
			updatedMetadata := &smartbft.Options{}
			if err := proto.Unmarshal(nextOrdererConfig.ConsensusMetadata(), updatedMetadata); err != nil {
				return errors.Wrap(err, "failed to unmarshal BFT metadata configuration")
			}

			_, err := util.ConfigFromMetadataOptions(1, updatedMetadata)
			if err != nil {
				return errors.New("invalid BFT metadata configuration")
			}

			err = validateBFTConsenterMapping(ordererConfig, nextOrdererConfig)
			if err != nil {
				return errors.Wrap(err, "invalid BFT consenter mapping configuration")
			}
		}

		logger.Infof("[channel: %s] consensus-type migration: about to change from %s to %s",
			mf.support.ChannelID(), ordererConfig.ConsensusType(), nextOrdererConfig.ConsensusType())
	}

	if nextOrdererConfig.ConsensusState() != ordererConfig.ConsensusState() {
		logger.Infof("[channel: %s] maintenance mode: ConsensusType.State about to change from %s to %s",
			mf.support.ChannelID(), ordererConfig.ConsensusState(), nextOrdererConfig.ConsensusState())
	}

	return nil
}

// ensureConsensusTypeChangeOnly checks that the only change is the Channel/Orderer group, and within that,
// only to the ConsensusType value.
func (mf *MaintenanceFilter) ensureConsensusTypeChangeOnly(configEnvelope *cb.ConfigEnvelope) error {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate the BFT metadata Consenters so each entry exactly matches an orderer's host, port, and TLS certificates in the next config
2. Review the wrapped inner error from validateBFTConsenterMapping for the specific mismatched consenter
3. Update TLS certs on the orderers first (separate maintenance update), then perform the type migration with matching consenter entries

Example fix

// before: consenter endpoint stale
{"Host": "orderer-old.example.com", "Port": 7050}
// after: matches next config orderer
{"Host": "orderer1.example.com", "Port": 7050}

// ensure every consenter matches an orderer endpoint/tls cert in the next config
for _, c := range opts.Consenters {
    if !ordererInNextConfig(next, c.Host, c.Port, c.ServerTlsCert, c.ClientTlsCert) {
        return fmt.Errorf("consenter %s:%d not present in next orderer config", c.Host, c.Port)
    }
}

When it happens

Trigger: Migrating to BFT where the Consenters list in smartbft metadata (host, port, client/server TLS certs) does not match the orderer nodes defined in the new config's Orderer group.

Common situations: Adding or removing an orderer node in the same update as the type change, stale TLS certificates in the consenters list, or endpoints copied from a different channel/environment.

Related errors

• node id mismatch
• failed to unmarshal BFT metadata configuration
• invalid BFT metadata configuration
• cannot get create BlockPuller
• failed getting a new bundle from envelope of config block

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