hyperledger/fabric · error

failed to unmarshal updated (new) etcdraft metadata configur

Error message

failed to unmarshal updated (new) etcdraft metadata configuration

What it means

After confirming the consensus type is etcdraft, MetadataFromConfigValue unmarshals the metadata field into etcdraft.ConfigMetadata. If proto.Unmarshal fails, the metadata bytes are not a valid ConfigMetadata and the update is rejected with this wrapped error.

Source

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

	}
	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 {
		if ordererConfigGroup, ok := update.GetReadSet().GetGroups()["Orderer"]; ok {
			if val, ok := ordererConfigGroup.GetValues()["ConsensusType"]; ok {
				baseVersion = val.GetVersion()
			}
		}
	}

	if update.GetWriteSet() != nil && update.WriteSet.Groups != nil {
		if ordererConfigGroup, ok := update.GetWriteSet().GetGroups()["Orderer"]; ok {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate the metadata with the matching Fabric version's etcdraft proto (e.g. via configtxlator) and resubmit the update
2. Align the config-generation tooling version with the orderer's Fabric version
3. Validate the marshaled metadata by round-tripping proto.Unmarshal locally before submitting

Example fix

// before
metadataBytes := []byte(jsonString) // not protobuf
// after
metadataBytes, err := proto.Marshal(&etcdraft.ConfigMetadata{Consenters: consenters})
if err != nil { return err }

// pre-validate metadata bytes before building the update
check := &etcdraft.ConfigMetadata{}
if err := proto.Unmarshal(metadataBytes, check); err != nil {
	return fmt.Errorf("metadata is not valid ConfigMetadata protobuf: %w", err)
}

func isRaftMetadata(b []byte) bool {
	md := &etcdraft.ConfigMetadata{}
	return proto.Unmarshal(b, md) == nil && len(md.GetConsenters()) > 0
}

md, ct, err := MetadataFromConfigValue(configValue)
if err != nil {
	if strings.Contains(err.Error(), "failed to unmarshal updated (new) etcdraft metadata") {
		return fmt.Errorf("raft metadata malformed — regenerate with matching Fabric version: %w", err)
	}
	return err
}

When it happens

Trigger: A config update of type etcdraft whose consensusType.metadata bytes are empty/corrupt or were produced with an incompatible etcdraft proto schema, failing proto.Unmarshal(consensusTypeValue.GetMetadata(), updatedMetadata).

Common situations: Config-update tooling from a different Fabric version emitting an older/newer metadata schema; truncation or manual assembly of the metadata bytes; switching from another consensus type with leftover garbage in the metadata field.

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 consensusType config update
• failed to unmarshal consensus metadata
• nil metadata
• could not read config update
• error unmarshalling ConfigEnvelope

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