hyperledger/fabric · error

failed to unmarshal consensusType config update

Error message

failed to unmarshal consensusType config update

What it means

MetadataFromConfigValue unmarshals the consensusType configuration value bytes from a channel config update into an orderer.ConsensusType protobuf. If proto.Unmarshal fails, the bytes are not a valid ConsensusType message, and the error is wrapped with this message. Callers such as MetadataFromConfigUpdate then abort processing the config update.

Source

Thrown at orderer/consensus/etcdraft/util.go:92

		clientKey := string(consenter.GetClientTlsCert())
		_, duplicateServerCert := seen[serverKey]
		_, duplicateClientCert := seen[clientKey]
		if duplicateServerCert || duplicateClientCert {
			return errors.Errorf("duplicate consenter: server cert: %s, client cert: %s", serverKey, clientKey)
		}

		seen[serverKey] = struct{}{}
		seen[clientKey] = struct{}{}
	}
	return nil
}

// MetadataFromConfigValue reads and translates configuration updates from config value into raft metadata
// In case consensus type is changed to BFT the raft metadata will be nil
func MetadataFromConfigValue(configValue *common.ConfigValue) (*etcdraft.ConfigMetadata, *orderer.ConsensusType, error) {
	consensusTypeValue := &orderer.ConsensusType{}
	if err := proto.Unmarshal(configValue.GetValue(), consensusTypeValue); err != nil {
		return nil, nil, errors.Wrap(err, "failed to unmarshal consensusType config update")
	}

	if consensusTypeValue.GetType() != "etcdraft" {
		return nil, consensusTypeValue, nil
	}

	updatedMetadata := &etcdraft.ConfigMetadata{}
	if err := proto.Unmarshal(consensusTypeValue.GetMetadata(), updatedMetadata); err != nil {
		return nil, nil, errors.Wrap(err, "failed to unmarshal updated (new) etcdraft metadata configuration")
	}

	return updatedMetadata, consensusTypeValue, nil
}

// MetadataFromConfigUpdate extracts consensus metadata from config update
func MetadataFromConfigUpdate(update *common.ConfigUpdate) (*etcdraft.ConfigMetadata, *orderer.ConsensusType, error) {
	var baseVersion uint64
	if update.GetReadSet() != nil && update.ReadSet.Groups != nil {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate the config update with a supported SDK/configtxlator so the ConsensusType message is correctly marshaled
2. Verify tooling and orderer are on compatible Hyperledger Fabric versions (protobuf schema alignment)
3. Inspect the config block with configtxlator to confirm the consensusType value decodes cleanly

Example fix

// before
cv.Value = manuallySerializedBytes
// after
value, err := proto.Marshal(&orderer.ConsensusType{
	Type: "etcdraft", Metadata: metadataBytes,
})
if err != nil { return err }
cv.Value = value

// pre-validate the config value bytes before processing
test := &orderer.ConsensusType{}
if err := proto.Unmarshal(configValue.GetValue(), test); err != nil {
	return fmt.Errorf("consensusType value is not a valid ConsensusType protobuf: %w", err)
}

func isConsensusTypeValue(b []byte) bool {
	ct := &orderer.ConsensusType{}
	return proto.Unmarshal(b, ct) == nil
}

md, ct, err := MetadataFromConfigValue(configValue)
if err != nil {
	if strings.Contains(err.Error(), "failed to unmarshal consensusType config update") {
		return fmt.Errorf("malformed consensusType value — regenerate with configtxlator: %w", err)
	}
	return err
}

When it happens

Trigger: A channel config transaction carries a consensusType value whose bytes are corrupted, truncated, or encoded by an incompatible protobuf version/schema, causing proto.Unmarshal(configValue.GetValue(), consensusTypeValue) to fail.

Common situations: Hand-crafted or SDK-generated config updates with malformed value payloads; version skew between config-generation tooling and orderer protobuf definitions; binary corruption in stored config blocks being replayed.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• failed to unmarshal updated (new) etcdraft metadata configur
• nil metadata
• nil consenter in metadata
• failed to extract envelope from the block
• could not read config update

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